# Toolkit User Guide

Welcome to the user guide for UDiTH Toolkit App.

# **Homepage**

The **Homepage** provides an overview of four sections: **Dashboard**, **Calendar**, **Subscriptions**, and **Notifications**, offering quick access to metrics, schedules, updates, and alerts to keep users informed and organized.

![The homepage](media/user_guide_homepage.png)

## Dashboard

The **Dashboard** offers a clear overview of punch items. Users can see the number of open, closed and past due punch items. Users can also see the overall workflow progress for the punch items.

![The dashboard](media/user_guide_dashboard.png)

## Calendar

The **Calendar** offers a timeline view, helping users track schedules, deadlines, and key project milestones.

![The calendar](media/user_guide_calendar.png)

## Subscriptions

The **Subscriptions** section enables users to monitor their subscribed punch items, providing quick access to key updates. Users can choose to view detailed information about each punch item or navigate directly to editing its fields, making it easy to stay informed and manage items efficiently.

## Notifications

The **Notifications** panel displays alerts and updates related to punch items, workflows, and system activities, ensuring users stay informed about important changes and actions requiring attention.

# Tickets

Users have three options to select from under the Tickets tab in the navigation bar: **Ticket List, Kanban Board & Progress Tracking**. Each will be detailed below.

![Punchlist options](media/user_guide_punchlist_options.gif)

## Ticket List

The **Ticket List** page provides users with an overview of all punch items associated with a project in a tabular format. It provides an interface for users to view, create, edit and delete punch items. It also offers tools for sorting, grouping, and customizing columns, as well as options to generate PDF reports and export data as XLSX files.

![The punch items page](media/user_guide_punch_items.png)

### **General Page Actions**

- Users can sort the punch items in ascending/descending, and alphabetical order by clicking the column headers of the table.

- Users can group the punch items by column by clicking on a header and dragging it to the section that says "**Drag a column header here to group by that column**".

- Users can utilize the drag-and-drop column picker to add and remove columns from the table.

- Users can generate a detailed PDF report for selected punch items by clicking the **"Generate PDF Report"** button (located to the right of the trash icon). To include a punch item in the report, ensure the checkbox to the left of its row is selected.
- Users can export data to an XLSX file by clicking the **"Export"** button (located to the right of the **"Generate PDF Report"** button). A prompt will appear, allowing users to choose between exporting the entire table or only the selected rows.

![Punch items page actions](media/user_guide_punch_items_actions.gif)

### **Filter Presets**

- Users can **select a saved filter preset** from the dropdown menu above the punchlist table. Selecting a preset instantly applies its saved filters, column layout, and sorting.

- To **save your current view as a new preset**, click the **Save Preset** button in the table’s toolbar. Enter a name for the preset, and it will be added to the preset selector for future use.
  - **Note:** If a preset with the entered name already exists, you will be prompted to enter a different, unique name.

- Users can **delete any preset** by selecting it in the dropdown and clicking the delete (trash) button.

- Users can **customize the table’s columns** using the **Column Picker**. Columns can be shown/hidden, and resized as needed.

- Users can **customize the table’s columns** using the **Column Picker**. Columns can be shown/hidden, and resized as needed.

- Users can **set a default preset** by selecting the radio/checkbox option next to a preset in the dropdown. The default preset is preserved between sessions and automatically applied when the page is reopened.

![Punchlist Table UI](media/user_guide_punchlist_preset.gif)

### **Creating a new punch item**

Users have four options when it comes to creating new punch items: **Create Blank, Create with Comment, Create from Template & Upload UPVF**. All four options can be accessed by clicking the drop-down arrow on the "**Create Ticket**" button and selecting the desired one.

1. **Create Blank**

- Clicking on the "Create Blank" option will open a popup prompting the user on if they would like to proceed with creating a new punch item.
- This punch item will be created with no information and it will require the user to navigate to the details page of that punch and populate it with information.

![Creating a new punch item with a blank template](media/user_guide_punch_item_creation_blank_template.gif)

2. **Create with Comment**

- To create a punch item with a comment, users must first select at least one object in the model. If no object is selected, the application will display a popup notifying the user of an invalid selection.
- When a valid selection is made, a popup window will appear, showing the number of objects selected and a dropdown menu for users to choose their desired object. The selected object will be the one used for attribute mappings when the **"Create"** button is clicked.
- The popup includes three textboxes: **Unit No**, **Pipeline**, and **Discipline**:
  - **Unit No**: Auto-populated from the Unit System attribute of the selected object and cannot be modified by the user.
  - **Pipeline** and **Discipline**: Can be filled in by the user and will be included in the comment of the created punch item.

- To finalize and create the punch item, users can click the **"Create"** button.

![Creating a new punch item with a comment](media/user_guide_punchlist_create_with_comment.gif)

3. **Create from Template**

The **Create from Template** option lets you create multiple tickets at once by uploading a spreadsheet file. It also supports updating existing tickets in bulk. The process follows a guided three-step workflow.

**Supported File Formats:**

- **CSV (.csv)** — Comma-separated values format
- **XLSX (.xlsx)** — Microsoft Excel spreadsheet format

#### Step 1 — Download the Template

When you select **"Create from Template"**, a popup appears with a download link. Click it to get a template file containing all available ticket fields as column headers. The first column is **TicketId**, followed by every detail field configured for your project.

Fill in the template with your ticket data — each row represents one ticket. You may leave the **TicketId** column empty if you plan to create all tickets as new (the system will assign IDs automatically).

#### Step 2 — Upload Your File

Click the **"Upload"** button in the popup and select your completed CSV or XLSX file. The system automatically validates the uploaded data:

- **Column names** must match existing ticket fields. Unrecognized columns are flagged as errors.
- **Data types** are checked — date fields must contain valid dates, number fields must contain numbers.
- **String length** — values exceeding 1,000 characters are rejected.

If validation errors are found, they are displayed so you can correct the file and re-upload.

#### Step 3 — Choose an Import Mode

After a successful upload, you are presented with three import mode cards:

| Mode                      | What it does                                                                                             |
| ------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Add if new**            | Creates tickets only for rows that do not already exist. Rows matching an existing ticket are skipped.   |
| **Overwrite if existing** | Updates existing tickets with the uploaded data. Rows that do not match any existing ticket are skipped. |
| **Add & Overwrite**       | Creates new tickets for new rows and updates existing tickets for matching rows.                         |

The system detects duplicates automatically by comparing the **TicketId** column in your file against tickets already in the database.

#### Advanced Options

Below the mode cards, an **"Advanced"** link reveals additional import settings:

- **Import all tickets as new** — When checked, every row in the file is created as a brand-new ticket with a system-generated ID, regardless of any TicketId values in the file. No duplicate detection runs in this mode.

- **Custom identifier field** — Instead of matching duplicates by TicketId, you can select any ticket field (e.g., Tag Number, Description) from the dropdown. The system will then match rows against existing tickets using that field's value. All three import modes remain available when a custom identifier is selected.

  > **Note:** When a custom identifier field is selected, any TicketId values in the file are ignored — matching is based solely on the chosen field.

#### Preview and Confirm

After selecting your import mode, click **"Import"**. A preview popup appears summarizing what will happen:

- **Tickets to add** — New tickets that will be created.
- **Tickets to overwrite** — Existing tickets that will be updated with new values.

Review the summary and click **"Confirm"** to proceed with the import.

#### Import Log

Once the import completes, a results popup shows how many tickets were created, overwritten, skipped, or failed. You can download a detailed **import log** file that lists the outcome for every row, including:

- Which tickets were created or overwritten
- What field values changed (showing old and new values for overwrites)
- Any rows that were skipped or failed, with reasons

![Creating a new punch item from template](media/user_guide_punchlist_create_from_template.gif)

4. **Upload UPVF**

- This option opens a popup prompting the user to upload a UPVF file.
- Once the file is uploaded and the **"Upload"** button is clicked, punch items will be created using the information from the file.

## Ticket Details

Users can access the user form of a specific punch item by double-clicking on a row in the main punchlist table. This action will open the page shown below.

![Punchlist details user form](media/user_guide_punchlist_details.png)

### Details

Upon opening this focused view, users are automatically directed to the **Details Tab**. This tab provides access to all punchlist fields which are defined by the administrator.

- Users can edit the punch item’s information directly within this tab, except for the textboxes in the top row.
- The fields in the top row are system-generated and updated by the program. These fields are not editable by users to ensure data integrity.

### Components

The **Components Tab** allows users to manage 3D and 2D components associated with a specific punch item, including adding, deleting, and interacting with the model.

- **Add and Delete Components:**
  - Users can add components to the punch item or delete them as needed.
  - To add all components currently selected in the model, click the **"Add Components"** button. This will add both 3D and 2D components currently selected.
  - To remove selected components from the punch item, click the **"Remove Selected Components"** button. This will delete both 3D and 2D components currently selected.
  - Individual components can be deleted from the table by clicking the trash icon at the end of the corresponding row.

- **Model Interaction:**
  - Users can interact with the model to focus on specific components.
  - In the top left corner, there is a **combo dropdown and button component** where users can define the desired model operations. After selecting a row from the table, these operations can be executed by clicking the button or by clicking on the row itself.

- **Table Configuration**
  - Users can configure their table view using the column picker.
  - The customized configuration is saved so that each user sees their own settings when they return to the table.
  - The first time a user accesses this page, the table configuration is set to the default based on the administrator's settings.
  - From that point on, any adjustments made via the column picker become the user's custom configuration.

- **Additional Options:**
  - **Clear Filter:** Removes any filters applied to the model.
  - **Select and Highlight All:** Selects and highlights all 3D components listed in the table.

![Punchlist details components](media/user_guide_punchlist_components.png)

### Attachments

The **Attachments Tab** allows users to manage files and attachments associated with a specific punch item.

- **Automatic Folder Creation:**
  - When a punch item is created and opened, a folder in UDiTH App is automatically generated, named after the punch ID.
  - Users can add files directly to this folder through the UDiTH App (e.g., photos, markups) and save it by clicking the **"Save Folder"** button.

- **UPVF History:**
  - Each time the folder is saved, a copy is stored. Previous versions of the folder can be viewed in the **UPVF History** section. They are organized by date, specifically by the year and the month they were saved.
  - Users can also open any of the previous folders in UDiTH App by clicking on that specific item.
  - The UPVF History can be toggled on or off using the **"UPVF History"** button located to the left of the **"Save Folder"** button.

- **Folder Updates:**
  - Whenever this punch item is opened in the detailed view, the application retrieves and displays the most recent version of the UDiTH App folder in the file tree.

- **Adding Files and Screenshots:**
  - Users can add files to the punch item by clicking the **"Add File"** button.
  - The attachments will appear in the main section of this tab, and users have the ability to click on it and download it locally. They also have the ability to delete it by clicking on the "X" in the top right corner of it.
  - Screenshots of the model can be taken using the **"Screenshot"** button.
    - Users can specify whether the screenshot should be set as the **initial screenshot** or the **final screenshot** of the punch item.
    - If available, the initial and final screenshots are displayed in the rightmost section of this tab.

- **Report Generation:**
  - Users can generate a detailed report for the punch item directly from this tab.
  - This report includes all details of the punch item and is identical to the report generated from the main punchlist table but is only for this specific punch item.

![Punchlist details attachments](media/user_guide_punchlist_attachments.png)

### Approvals

In the **Approvals Tab**, users can manage workflows for a punch item.

- **Assigning Workflows:**
  - Click the **"Assign Workflow"** button to open a popup prompting the user to select a workflow from a list of available options, defined by the application administrator.
  - After selecting a valid workflow, click the **"Add Workflow"** button to assign it to the punch item.

- **Workflow Overview:**
  - Once added, the workflow will appear on the page, outlining all the steps required to complete the punch item along with their details.
  - Users can assign multiple workflows to a single punch item and toggle between them using the dropdown menu to the right of the **"Assign Workflow"** button.

- **Step Status Indicators:**
  - Each workflow step is marked with a colored circle to indicate its status:
    - **Grey:** Not started.
    - **Yellow:** In progress.
    - **Green:** Approved.
    - **Red:** Disapproved.
  - Steps must be completed in sequential order and cannot be skipped.

- **Additional Actions:**
  - **Show Flowchart:** Click the **"Show Flowchart"** button to display a flowchart representation of the workflow. Click the button again to hide it.
  - **Delete Workflow:** Remove a workflow by clicking the **"Delete Workflow"** button.
  - **Show Hidden Steps:** Toggle hidden steps on or off using the **"Show Hidden Steps"** button.

- **Interacting with Workflow Steps:**
  - To interact with a step users can click on it directly. This will open the popup seen below. From here a user has the ability to approve or disapprove this step and add notes on their decision. Once again, steps must be completed sequentially so if a step that has not been started yet is selected, it will not have the ability to be approved or disapproved.

![Punchlist details approvals pop-up](media/user_guide_punchlist_approvals_popup.gif)

### Additional Features

- **Back Button:**
  - The focused view includes a **Back** button in the top-left corner of the navigation bar. Clicking this button will redirect users back to the previous page they were on.

- **Activity Chat:**
  - An activity chat is visible on the right side of the page, tracking all changes and interactions related to the punch item.
  - Users can also send messages through the activity chat to share additional information as needed.
  - The activity chat can be toggled on or off using the **chat icon** in the top-right corner.

![Punchlist details approvals page](media/user_guide_punchlist_approvals.png)

## Kanban Board

The **Kanban Board** allows users to view, sort, filter, organize, and plan the execution of punch items effectively.

### Grouping Options

1.  **Field-Based Grouping:**
    - Users can group punch items by specific fields using the **dropdown menu** in the top left corner.
    - All punch items with the same value for the selected field will be grouped together in the main section.
    - Each punch item is represented by a card containing information defined by the application administrator.

2.  **Workflow-Based Grouping:**
    - When grouping by **Workflow**, an additional **dropdown menu** appears, allowing users to specify which workflow to group by.
    - In this view:
      - List headers represent the individual steps of the selected workflow.
      - Cards (tickets) are placed in lists corresponding to their current workflow step.
    - The workflow view within the Kanban board provide users a focused grouping of tickets implementing the selected workflow.

![Workflow dropdown](media/user_guide_kanban_dropdown.png)

### Workflow Step Advancement

- Users can adjust a ticket's current step by dragging and dropping the card a maximum of one step.
- Upon dragging a card, a popup will appear prompting the user to either approve or disapprove the step.

- Users can advance a ticket to the next step of the workflow by dragging and dropping the card a step forward:

![Board actions](media/user_guide_kanban_drag.gif)

- Alternatively, users can set back a tickets workflow progress by dragging and dropping the card a step backward:

![Board actions](media/user_guide_kanban_backwards.gif)

- For streamlining the approval / denial actions for multiple tickets, utilize the checkbox and then perform the actions to apply changes to the selected tickets:

![Simultaneous actions](media/user_guide_kanban_simul.gif)

- Actions configuring a ticket's workflow status require confirmation to persist.
- Users are given the option to attach a note to a step action approval / denial, detailing the decision with supplementary information.
- The approval / denial of workflow steps occurs in the confirmation popup. Users finalize the action by utilizing the confirmation buttons.
  - Clicking the edit button on the ticket card instead of utilizing the drag-and-drop feature makes both actions simultaneously accessible.

![Both at once](media/user_guide_kanban_both.gif)

### Kanban Board & Approvals Tab Sync

- The workflow actions performed for a ticket in the Kanban board directly impacts the Approvals tab within the same ticket.
- When navigating to the ticket's Approvals tab (Double-clicking on the card in the kanban board for a streamlined flow), workflow step changes are synced to those performed in the kanban board.

![Approvals tab](media/user_guide_approvals.png)

### Additional Features

- **Navigating to Ticket Details:**
  - Users can double-click on a card to open the detailed view of the selected punch item.

![Planning page](media/user_guide_planning.png)

## Progress Tracking

The **Progress Tracking** page provides a comprehensive overview of all punch items, including the workflows assigned to them, their current workflow step, and the overall progress of each workflow.

- **Overview Panel:**
  - On the right side of the page, an overview displays the total number of open and closed workflows across the application.

- **Exporting Data:**
  - Users can export the entire table or selected rows as an XLSX file by clicking the **Export** dropdown button.

- **Customizing Columns:**
  - The visible columns in the table can be customized using the **Column Picker** button, located to the left of the search bar.

- **Navigating to Ticket Details:**
  - Users can open the detailed view of a punch item by double-clicking on a row.

![Workflow tracking page](media/user_guide_workflow_tracking.png)

# **General Settings**

The General Settings page allows users to personalize their experience within the application by configuring visual themes, interface language, and a custom email signature.
To access this page, click the settings gearwheel icon at the bottom of the navigation bar.

## **Theme Settings**

Users can personalize the visual style of the application by choosing a theme from the theme settings section on the settings page.

- Use the dropdown menu to pick a theme that suits your preference (e.g., Dark Theme).

- Changing the theme updates the application's appearance, including colors, fonts, and interface elements, to reflect the selected design.

- The chosen theme is linked to your account and is automatically applied whenever you log in, ensuring a consistent experience across sessions.

![Setting Theme](media/user_guide_set_theme.gif)

## **Language Options**

Within the General Settings page, users can configure their preferred language using the options available in the Language Settings section.

- Under language settings, select your preferred language from the dropdown menu (e.g., `en-US`, `ko`, `he`, `ar`).

- Once selected, the interface will update immediately to reflect the chosen language. All labels, buttons, messages, and other text elements throughout the application will display in the selected language.

- Your selected language is saved to your profile and persists between sessions. Each time you log in, the application automatically applies your saved language preference.

- You may also select **"Default"** to always follow the system's default language as configured by the administrator. If the administrator changes the default language, your interface will update accordingly.

- If a translation is missing in your selected language, the application falls back in order to:
  1. The standard translation in the selected language
  2. The custom translation in the system default language
  3. The standard translation in the system default language

- **Right-to-Left (RTL) Support**: When a Right-to-Left language such as Arabic or Hebrew is selected, the entire interface layout automatically mirrors to support RTL reading. Text alignment, navigation menus, and all UI components adjust from right to left.

- **Note**: Only languages that have been configured by the administrator appear in the dropdown. If you need a language that is not listed, contact your administrator.

![Setting Language](media/user_guide_set_language.gif)

## **Signature Settings**

The signature settings section on the settings page allows users to define their personal email signature.

- This signature is automatically appended to the message body when composing an email.

- The signature is stored with the user’s profile and is automatically applied in future sessions, removing the need for repeated entry.

![Setting Language](media/user_guide_signature.png)

# **Master Work Programs**

The **Master Work Programs** page provides an overview of all LOTO work programs with customizable columns, inline editing, grid preferences, and work program locking.

## Overview

This page allows users to view, create, edit, and manage work programs. The data grid supports custom columns configured by administrators, along with user-specific preferences for column layout, filtering, and sorting.

## Features

### 1. Data Grid Customization

- **Column Filtering**: Click column headers to filter data
- **Column Reordering**: Drag column headers to rearrange
- **Column Resizing**: Drag column borders to resize
- **Sorting**: Click headers to sort ascending/descending
- **Header Filters**: Use the dropdown filters in column headers to filter by specific values

### 2. Custom Columns

The grid displays both system columns and custom columns configured by administrators:

- **System columns**: Work Program Name, SAP Number, Description, Created By, Last Modified, Last Modified By, Equipment, Status, Editing
- **Custom columns**: Additional columns defined in admin settings (e.g., Project Phase, Priority, Department)

Custom column values can be edited inline when the work program is not locked.

### 3. Inline Editing

- **Single-click** on a row to enter edit mode for custom column values
- **Double-click** to navigate to the work program details page
- Changes to custom column values are saved automatically

### 4. Grid Preferences

Your column layout, filters, and sorting preferences are saved automatically:

- Preferences persist across sessions
- Each user has their own saved preferences
- Click **Reset Formatting** to restore the default view

### 5. Work Program Locking

When another user is editing a work program, the row displays:

- Yellow background color
- Italic text styling
- Editor's name in the "Editing" column

When attempting to open a locked work program, you have three options:

- **Cancel**: Return to the list without opening
- **View Only**: Open the work program in read-only mode
- **Override**: Force release the lock and take over editing (use with caution)

### 6. Creating Work Programs

1. Click the **Start New Program** button
2. Fill in the work program details in the creation form
3. The new program appears in the grid

### 7. Deleting Work Programs

1. Click the **trash** icon on a row (only visible if the program is not locked)
2. Confirm deletion in the popup
3. The work program is soft-deleted (data preserved for recovery if needed)

# **P&ID Multi-Use Blinds**

The **P&ID Multi-Use Blinds** feature enables users to visualize, manage, and interact with sketch items (e.g., Blinds, Valves, Hoses) on active piping and instrumentation diagrams (P&IDs). Users can display both current and external work program items directly within the IntelliPID interface

## Adding List Items

Users within a work program can click the **Add list item** button to create a new entry for the selected list type.

- Items available include **Blinds, Hoses, Valves, Electrical Drives**, or other components, depending on the selected list type.
- When clicked, the application opens the **Sketching Tool** and lets you place catalogue items directly onto the 2D viewer. After placement, the tool switches to a details form where you can review and edit fields (a mix of user-entered and model-derived values). Submitting the form finalizes the new list item and adds it to the data grid for the active list type.

#### Steps to Add

1. **Open the Sketching Tool**
   Click **Add list item**. The **Sketching Tool** popup opens and displays the catalogue items available for placement on the active PID.

2. **Choose a Catalogue Item**
   In the popup, select the item and the specific catalogue entry you want to add.

3. **Place the Item on the 2D Viewer**
   Move your cursor over the 2D viewer window; a placement preview follows your cursor. Click to place the item at the desired location.

4. **Item is Created Automatically**
   After placement, the system auto-submits the item using the default field values. The list item is immediately created, linked to its placement on the PID, and added to the data grid for the active list type — no manual confirmation step is required.

   > **Note:** The **Type** column is a special system column that automatically displays the **Connected Item Name** (the name of the catalogue item placed on the P&ID). This value is set during placement and reflects which catalogue entry was selected.

5. **Re-select from the Table (Optional)**
   Click the item's row in the data grid to automatically load the 2D viewer window with that item selected and fitted to the viewport for easy inspection.

![Add list item](media/user_guide_add_list_item.gif)

### Automatic NoOnPID Generation

When a catalogue item or primitive is placed on the P&ID, the system automatically generates a **NoOnPID** identifier for the new list item. This identifier provides a sequential label that uniquely numbers each item within its list type for the current work program.

#### How It Works

- Each list type has a designated **prefix**:

  | List Type              | Prefix |
  | ---------------------- | ------ |
  | Blind List             | S      |
  | Valves List            | A      |
  | Electrical Drives List | E      |
  | Drains List            | D      |
  | Hose List              | H      |
  | Isolation Markup       | C      |

- The **number** following the prefix is determined by counting existing items of that list type in the work program and incrementing by one.
- For example, if a work program already has 3 items in the Valves List, the next placed valve will receive the NoOnPID **A4**.

### Editing List Items

Users can edit an existing list item directly from the data grid.

- Supported item types include **Blinds, Hoses, Valves, Electrical Drives**, and other components depending on the selected list type.
- Edits apply to the item's **placement** in the 2D viewer and its **connecting point(s)**. Changes are reflected immediately in the data grid.

#### Steps to Edit

1. **Enter Edit Mode**
   In the data grid, click the **Edit** (pencil) icon on the item row you want to modify. The P&ID sketch opens in the 2D viewer and **all rows that share the same P&ID** switch to edit state, allowing you to reposition any item on that sketch.

2. **Adjust Placement (2D Viewer)**
   Click and drag the item to the desired new location within the 2D viewer.

3. **Update Connecting Point(s)**
   Select the item's connector handle(s) and connect it to the new IntelliPID segment or target. This will update the appropriate value in the table.

4. **Rotate the Symbol (Optional)**
   While in edit mode, you can rotate the placed symbol for any row in 15° increments using two methods:
   - **R key (keyboard):** Press **R** while the data grid has focus. The symbol's rotation attribute is updated immediately. The visual change in the IntelliPID viewer will appear after you save.
   - **Rotate button (click):** Click the **Rotate** button in the row's action column (visible only while in edit mode). This triggers an immediate visual refresh in the IntelliPID viewer so you can see the rotated position before saving.

5. **Save Changes**
   Click the **Save** icon (visible on all rows sharing the same P&ID while in edit mode) on any of those rows to finalize your updates. All edited rows are saved together.

![Position Edit](media/user_guide_edit_list_item.gif)

#### Edit Values in Table

1. **Start Inline Edit**
   Double-click the cell in the data grid to activate its editor (e.g., text, dropdown, date).

2. **Enter New Value**
   Type or select the new value. Required fields must be valid before saving.

![Table Values Edit](media/user_guide_edit_list_item_value.gif)

### Deleting List Items

1. Click the **Trash** icon on the list item row
2. Confirm deletion

**Important**: Deleting a list item removes it from the database and the associated symbol from the P&ID (if placed).

### Nearby Work

Users working on a specific PID can click the **"Nearby Work"** button to automatically visualize all catalogue items that are associated with active work programs on that PID.

- Items displayed include **Blinds, Hoses, Valves, Electrical Drives**, or other components, depending on the selected list type.
- Once clicked, the application:
  - Fetches all sketch items from work programs linked to the opened PID or the same equipment tag.
  - Displays them directly within the active drawing view.
  - Enables contextual mapping between the sketch item and the IntelliPID segment selected.

![Nearby Work](media/user_guide_load_blinds.gif)

### Copying External Blinds

Blinds from **external work programs** (not currently active in the PID view) can be cloned into the current work program list.

#### Steps to Clone:

1. Click the **Planning** toggle to view external work program items (highlighted in yellow).
2. Click the **Copy** button next to the desired blind.
3. A **Clone Tool popup** will appear, prompting the user to place the blind into the drawing:

![Clone Tool](media/user_guide_clone_1.gif)

4. Upon placement:
   - The blind is rendered on the PID.
   - Metadata is fetched and pre-fills the Clone Tool popup.

![Clone Tool Details](media/user_guide_clone_2.gif)

### Multi-Use Blind Naming Convention

If a blind is reused across multiple work programs, it will reflect this in the naming convention shown in the data grid.

Format: `<BlindName>M<X>`

- Example: A blind named **S1** used in **two** other work programs will appear as **S1M2**.

### Interacting with P&ID Viewer

The P&ID viewer integrates with the list table:

**Select an item in the table**:

- Click a row in the list table
- The P&ID viewer automatically pans and zooms to that item's symbol
- The symbol is highlighted

**Select an item in the P&ID**:

- Click a symbol in the P&ID viewer
- The corresponding row in the table is highlighted

**Clear filters**:

- Click **"Clear Filter"** to reset the P&ID view

**Fit to view**:

- Select an item to automatically fit it to the viewport

## Steps Table

Each work program includes a **Steps Table** organized by phase tabs: **Preparation**, **De-commissioning**, **Repair**, and **Commissioning**. The steps table tracks the procedural steps required for each phase of the work program.

### Steps Table Columns

The steps table displays the following system columns plus any administrator-configured dynamic columns:

| Column              | Description                                                                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Order**           | Sequential number determining execution order (drag to reorder)                                                                                                              |
| **Step Title**      | Name/description of the step                                                                                                                                                 |
| **Item Type**       | Classification of the step, including the phase it belongs to                                                                                                                |
| **Dynamic Columns** | Additional columns configured by administrators for the current phase (e.g., Responsible Party, Action Owner). These vary per phase based on the metadata field definitions. |
| **Comment**         | Notes, instructions, or additional details                                                                                                                                   |
| **Interdependency** | Other steps (by Order number) that must be completed first                                                                                                                   |
| **Attachments**     | File attachments associated with the step                                                                                                                                    |

### Working with Steps

- **Add a step**: Click the **Add (+)** button while on the desired phase tab
- **Edit a step**: Click the **Edit (pencil)** icon or double-click a cell to edit inline
- **Delete a step**: Click the **Trash** icon on the step row
- **Reorder steps**: Drag using the handle at the left of each row
- **Set interdependencies**: Select prerequisite steps in the Interdependency column

### Importing Steps from Templates

When importing steps from a template (via the **Planning → Template** tab), all step data is copied including any values entered in dynamic columns. This means template steps can be pre-configured with dynamic field values that carry over to the work program.

Similarly, when cloning steps from another work program, dynamic field values are preserved in the copy.

## Summary Tab

The **Summary** tab provides an overview of the entire work program and generates comprehensive reports.

### Summary View

The Summary displays:

- **Work Program Header**: Name, SAP Number, Equipment details
- **Phase Summaries**: Count of steps per phase and completion status
- **List Summaries**: Count of items per list type
- **Metadata Preview**: Key fields configured to appear in summary reports (by administrators)

![Summary Tab](media/user_guide_loto_summary.png)

### Generating Reports

1. Navigate to the **Summary** tab
2. Review the summary information
3. Click **"Print all"**

The system generates a comprehensive PDF report and downloads it to your local machine. What the PDF contains depends on whether a print summary template has been configured by your administrator.

#### Standard Report (no template active)

When no template is active, the report includes:

- Work Program header information
- All steps from all phases with status
- All list items with their metadata
- P&ID sketches showing item placements

> **Note:** Boolean metadata fields (e.g., checkboxes) are displayed as a centered **"X"** for true values and left blank for false values in the standard PDF tables.

#### Template-Based Report (template active)

When an administrator has uploaded and activated a print summary template, the PDF is generated from that Excel-based layout instead. The template is pre-designed by your administrator to match your organisation's reporting format.

The template-based PDF:

- Uses the layout, colours, fonts, and section structure defined in the Excel template
- Fills `#FieldName` placeholders in the template with the work program's actual data (name, SAP number, equipment, dates, and any configured metadata fields)
- Lists P&ID drawing names in the section marked `#PIDSketches`
- Preserves any images embedded directly in the Excel template (logos, diagrams, icons) at their original position and size
- Appends captured P&ID sketch PDFs after the template pages, preserving all model layers
- Includes **interactive fields** you can fill in directly inside a PDF reader:
  - **Checkboxes** — cells marked as boolean in the template are rendered as tickable checkboxes
  - **Comment fields** — cells marked with `#Comment` become editable text fields you can type into
  - **Dropdown checklists** — dropdown metadata fields using a `#FieldName` token show all options with the current value pre-checked
  - **Inline dropdown values** — dropdown metadata fields using a `##FieldName` (double hash) token display only the selected value as plain text, without a checklist

> **Note:** If the work program is open in the model viewer, the system captures fresh P&ID sketches before generating the template PDF to ensure the connection to the model stays active. This may cause a brief delay before the download begins.

## View-Only Mode

If you open a work program that's locked by another user and choose **"View Only"**, the interface operates in read-only mode:

- All edit buttons are disabled
- You can view steps, lists, and details
- You cannot add, edit, or delete items
- The breadcrumb indicates "View Only" status

**Exiting View-Only Mode**: Close the work program and return later when the lock is released.

## Saving Work

**Auto-Save**: Changes to steps and list items are saved immediately when you press Enter or click elsewhere.

**UPVF Folder**: The work program maintains a UPVF folder containing:

- P&ID sketches with placed symbols
- File attachments
- Document history

**Folder Save**: The UPVF folder is automatically saved when you navigate away or close the work program.

**Best Practice**: Periodically verify your changes are saved, especially after placing multiple items on P&IDs.

## PowerBI ##
### Getting Information from PowerBI Report ###
- After you have created your Report, open "Share" -> "Link to this Visual" in PowerBI 

 ![Get Link from PowerBI](media/user_guide_powerbi_getlink.png)
- Copy the Link to a Text Editor, it will look something like this:
  -  https://app.powerbi.com/groups/< HERE IS WORKSPACE ID>/reports/< HERE  IS REPORT ID>/...
- Copy both values, they are required for Toolkit.

### Adding a new Report ###
- Click the + Button to add a new Report

![Add PowerBI Report](media/user_guide_powerbi_additem.png)
- Enter 'Report Name' (it's not necessary to use the same as in PowerBI, it's just for Toolkit)
- 'Report ID' which we got from the PowerBI URI (see *Getting Information from PowerBI Report*)
- 'Workspace ID' which we got from the PowerBI URI  (see *Getting Information from PowerBI Report*)
- 'Type report type' is used for grouping reports, if already a group exists, you can select it or provide any useful name for it.

### Troubleshooting ###
New report should now be available under the selected/created group. 
- If there aren't any entries, verify with your Admin, that:
  - Azure App Client ID, Client Secret and Tenant ID are set as Environment Variables for the Toolkit Server
  - Azure App Client has permissions in your PowerBI workspace
  - PowerBI Report ID and Workspace ID are correct

## Troubleshooting Common Issues

### "Invalid Selection" Error When Creating Work Program

- **Cause**: Selected objects have multiple different Tags or no Tag
- **Solution**: Ensure all selected objects share the same unique Tag value

### Cannot Complete a Step

- **Cause**: Step has interdependencies that are not yet complete
- **Solution**: Complete prerequisite steps first (check the Interdependency column)

### Symbol Not Appearing After Placement

- **Cause**: SVG file path is invalid or file is missing
- **Solution**: Contact your administrator to verify catalogue item configuration

### "Work Program Locked" Message

- **Cause**: Another user is currently editing the work program
- **Solution**: Wait for them to finish, use "View Only" mode, or coordinate to override

### Changes Not Saving

- **Cause**: Concurrent edit conflict or network issue
- **Solution**: Refresh the page and re-enter changes; contact support if persistent

### List Item Missing from P&ID

- **Cause**: Item was added without P&ID placement, or UPVF folder not saved
- **Solution**: Edit the item and place it on the P&ID; ensure folder is saved

## Additional Notes

- **Work Program Status**: Administrators may configure workflow status fields (e.g., Draft, In Progress, Complete, Closed)
- **SAP Integration**: If configured, work programs can link to SAP work orders for seamless ERP integration
- **Equipment Hierarchy**: Functional Location and Equipment Type help organize and filter work programs
- **Reusing Work Programs**: Mark work programs as "Reused" to indicate they've been applied to multiple scenarios