# Linking and API

## Link Files

-   To link an object to an external source, use a **link file**.
-   For linking from an external source to an object in UDiTH, use **deep linking**.

**Deep linking API: Link from outside \> UDiTH \> Link to outside**

UDiTH uses link files to store link information. Link files are loaded automatically when you open UDiTH, but you can also load them manually at any time via **File management > Load a link file** (<img src="./media/ButtonLoadLinkedFile.png" width="21" height="22">).

## Create a Link File

Link files are created in Excel. The file should contain the following columns:

<table>
<tr><th>Condition</th><th>Link</th><th>Name</th></tr>
<tr><td>

Task=Piping

</td><td>

https://www.caxperts.com/

</td><td>

Homepage

</td></tr>
<tr><td>

Task=Structure

</td><td>

https://en.wikipedia.org/wiki/Structure

</td><td>

Wikipedia

</td></tr>
</table>

-   **Condition** can be any attribute. `*` can be used as a wildcard to select every object.

For example: `Task=*`

-   **Link** can be a URL or a local path. Absolute and relative paths are supported using the backslash `\`.

Example of a local path: `data\docs\Valve.pdf`

-   **Name** is the text displayed in UDiTH for the link.

## Links in Isometrics

UDiTH automatically links objects in 3D models with their corresponding symbols in isometric and P&ID drawings. As a result, you can access drawings from both the **2D and P&ID** level of your project tree and the link list.

You can select an object in the 3D model by clicking on a symbol in a drawing. The symbol is highlighted when you hover your mouse pointer over it:

<img src="./media/image187.png" width="300" height="166"><img src="./media/image188.png" width="207" height="171">

Because drawings are rendered in PDF format, you can zoom in without any loss of quality.

You can also generate a double-sided ISO PDF and preview the 3D objects to be included.

> Links to objects in the 3D model are not retained.

## Deep Linking

You can use deep links in documents such as Word files, websites, and emails to open UDiTH and execute specific queries and commands.

Deep linking uses the URL handler `upvapi://`.

**Structure:**

`upvapi://<MODEL-URL>?<QUERY>&<COMMANDS>`

**Example:**

`upvapi://http://demo.universalplantviewer.com/demoPlant/4/0?Name=K-001&NozzleName=N3&CMD!Select&CMD!Fit&CMD!Highlight`

**Wildcards:**

Use `_` for any single character and `*` for any number of characters.

**Example:**

`upvapi://http://demo.universalplantviewer.com/demoPlant/4/0?Name=K-001&NozzleName=N3&CMD!Select&CMD!Fit&CMD!Highlight`

This looks for Nozzle 3 on object `K-001`, selects it, fits it to the screen, and greys out all other objects.

### `UDiTHSelected`

By adding `UDiTHSelected=true` or `UDiTHSelected=false`, you can limit the query to items that are currently selected or not selected in UDiTH.

**Example:**

`upvapi://http://demo.universalplanviewer.com/demoPlant/5/0?Name=D-100&UDiTHSelected=true&CMD!Select&CMD!Fit&CMD!FocusViewer&CMD!Combine=Or`

In this example, `Combine=Or` adds all items with `Name=D-100` to the current selection.

> Broken links, for example those caused by typing mistakes, do not produce an error message.

### Building Deep Links with Excel

In Excel, you can use the `CONCATENATE` and `HYPERLINK` functions to build a list of links easily.

Enter your model URL or path together with columns for the attributes, values, and commands you want to include:

> Paths may not work if they contain special characters. Use a URL encoder to ensure that the paths are correct.

<table>
<tr><th></th><th>A</th><th>B</th><th>C</th></tr>
<tr><td>

1

</td><td>

Model URL

</td><td>

...

</td><td>

-

</td></tr>
<tr><td>

2

</td><td>

Attribute

</td><td>

Value

</td><td>

Commands

</td></tr>
<tr><td>

3

</td><td>

Name

</td><td>

D-100

</td><td>

CMD!Fit

</td></tr>
<tr><td>

4

</td><td>

Task

</td><td>

Piping

</td><td>

CMD!SetVisibility=false

</td></tr>
<tr><td>

5

</td><td>

Pipeline

</td><td>

S-1672

</td><td>

CMD!Select&CMD!IntelliClip=1

</td></tr>
<tr><td>

6

</td><td>

Task

</td><td>

\*

</td><td>

CMD!SetCameraView=3037!2476!72!180!180!10

</td></tr>
<tr><td>

7

</td><td>

...

</td><td>

</td><td>

</td></tr>
</table>

Then add a function using the following structure:

`=HYPERLINK(CONCATENATE("upvapi://";$B$1;"?";A4;"=";B4;"&";C4))`

**Table 1: Commands**

<table>
<tr><th>Command</th><th>Description</th></tr>
<tr><td>

ClearClipping

</td><td>

Disables clipping.

</td></tr>
<tr><td>

ClearColor

</td><td>

Restores the original object colours.

</td></tr>
<tr><td>

ClearCustomAttributes

</td><td>

Resets all changes made to custom attributes during the current session.

</td></tr>
<tr><td>

ClearHighlight

</td><td>

Disables highlighting.

</td></tr>
<tr><td>

ClearLinks

</td><td>

Removes links loaded from link files.

</td></tr>
<tr><td>

ClearSelection

</td><td>

Clears the current selection.

</td></tr>
<tr><td>

Color

</td><td>

`Color=[HTML colour code]` using the format `#RRGGBB` or `#RRGGBBAA`.
**Example:** `CMD!Color=#FF0000`

</td></tr>
<tr><td>

Combine

</td><td>

`Combine=[OR/AND]` uses `OR` between query conditions instead of `AND`, which is the default.

</td></tr>
<tr><td>

ExportPackageFile

</td><td>

Exports package files to the specified path.

</td></tr>
<tr><td>

Fit

</td><td>

Optional parameter: `Centred`.
`true` (default): fits to the centre of the box.
`false`: fits to the screen borders of the current view.
**Example:** `CMD!Fit=true`

</td></tr>
<tr><td>

Highlight

</td><td>

Highlights the specified object.
**Example:** `Name=D-100&CMD!Highlight`

</td></tr>
<tr><td>

IntelliClip

</td><td>

`IntelliClip=[distance in metres]`
Values `> 0` display only the object. `0` also displays objects touching the selected object. Decimal values are supported.

</td></tr>
<tr><td>

LoadColorFile

</td><td>

`LoadColorFile=[online or offline location]`
Local:
`CMD!LoadColorFile=C:\colors.xlsx`

Via HTTP:
`CMD!LoadColorFile=http://example.com/colors.xlsx`

Via UNC:
`CMD!LoadColorFile=file://////server/share/colors.xlsx`

Note: for UNC paths, it is important to use six slashes (`//////`) after `file`.

**Examples:**

`CMD!LoadColorFile=c:\colors.xlsx`
`CMD!LoadColorFile=http://demo.universalplantviewer.com/demoPlant/4/0/colors.xlsx`

</td></tr>
<tr><td>

LoadConfigFile

</td><td>

Loads a configuration file.
Parameters:
- configuration file name
- combine mode (optional)

By default, existing settings are cleared. `Merge` keeps existing views and merges them, overriding existing values with those from the configuration file.

**Example:** `C:/config.upv!Merge`

</td></tr>
<tr><td>

LoadLinkFile

</td><td>

`LoadLinkFile=[online or offline location]`

Local: `CMD!LoadLinkFile=C:\links.xlsx`

Via HTTP: `CMD!LoadLinkFile=http://example.com/links.xlsx`

Via UNC: `CMD!LoadLinkFile=file://////server/share/links.xlsx`

Note: for UNC paths, it is important to use six slashes (`//////`) after `file`.

</td></tr>
<tr><td>

LoadPackageFile

</td><td>

Loads package files from the specified path.

Parameters:
Parameters:
- URL
- `Replace` (optional). If set to `true`, current packages are replaced instead of being added to the existing ones.

**Example:**
`CMD!LoadPackageFile=c:\package.upvf!true`

</td></tr>
<tr><td>

LoadSketch

</td><td>

Loads a sketch from the specified path.
A second parameter can be used to rename the sketch.
**Example:**
`CMD!LoadSketch=C:\Sketch\SketchFile.upvsk!NewName`

</td></tr>
<tr><td>

ResetView

</td><td>

Resets the camera mode, camera position, rotation, and states such as highlighting to the state used when the model was loaded.

</td></tr>
<tr><td>

SearchFallback

</td><td>

This command automatically adds the search string to the search box. If the exact search returns no results, a fuzzy search is started automatically.

**Example:**
`upvapi://http://demo.universalplantviewer.com/demoPlant/4/0?Name=E240&NozzleName=N8&CMD!Select&CMD!Fit&CMD!Searchfallback`

This starts a search and finds Nozzle N8 on equipment E-240.

</td></tr>
<tr><td>

Select

</td><td>

Selects the specified object.
**Example:**
`Name=D-100&CMD!Select`

</td></tr>
<tr><td>

SetCameraView

</td><td>

`SetCameraView=[X!Y!Z!rotationX!rotationY!rotationZ]` using Euler angles.

**Example:**
`CMD!SetCameraView=3037!2476!72!180!180!90` sets the camera to coordinates `3037` (X), `2476` (Y), and `72` (Z = height), facing parallel to the ground and rotated `90°` to the left.

</td></tr>
<tr><td>

SetCameraViewLookAtTarget

</td><td>

`SetCameraViewLookAtTarget=[X!Y!Z!TargetX!TargetY!TargetZ]`
Moves the camera to the specified location and points it towards the target location.

</td></tr>
<tr><td>

SetClippingPlane

</td><td>

Sets the visible camera view distance.
The first parameter is the minimum distance for visible objects, and the second is the maximum distance.
**Example:** `CMD!SetClippingPlane=20!30`

</td></tr>
<tr><td>

SetTreeConfiguration

</td><td>

`SetTreeConfiguration=[discipline!discipline...]`
**Example:**
`CMD!SetTreeConfiguration=Task!SystemPath`

</td></tr>
<tr><td>

SetVisibility

</td><td>

`SetVisibility=[True/False]`

</td></tr>
<tr><td>

SetVisibleAspects

</td><td>

`SetVisibleAspects=[aspect!aspect]`
**Example:**
`CMD!SetVisibleAspects=Simple Physical!Insulation` shows both insulation and simple physical.

</td></tr>
<tr><td>

ShowOnly

</td><td>

Sets all query objects to visible and hides all other objects.

</td></tr>
<tr><td>

ShowMessage

</td><td>

Shows a message and title in a message box.
**Example:** `CMD!ShowMessage=Your Message!Your Title`

</td></tr>
<tr><td>

TakeAndSaveScreenshot

</td><td>

Takes a screenshot using the following parameters, in this order:

- path where the image is to be stored
- width in pixels
- height in pixels
- field of view in degrees (`> 160` may produce incorrect images)
- format, either `.png` or `.jpg`
- hide UI, `true` or `false`
- enable anti-aliasing, `true` or `false`
- enable transparent background, `true` or `false`
- model in best quality, `true` or `false`

**Example:** `CMD!TakeAndSaveScreenshot=C:\Test\image.jpg!2000!1500!120!png!true!true!true!false`

</td></tr>
<tr><td>

VolumeClip

</td><td>

`VolumeClip=[distance in metres]`
Values `< 0` are treated as `0`. Decimal values are supported.

</td></tr>
<tr><td>

VolumeClipByCoordinates

</td><td>

Runs the volume clip algorithm using a bounding box defined by the following parameters:
- X min
- Y min
- Z min
- X max
- Y max
- Z max

**Example:** `CMD!VolumeClipByCoordinates=-10.0!-10.0!-10.0!20.0!20.0!20.0`

</td></tr>
</table>

**Wildcards:**

-   **\*** = any character

-   **\_** = any single character

### Condition Operators

By default, query conditions are combined using **AND**:

For example:
```
Name=K-001&NozzleName=N5
```

However, you can use **OR** with the combine command:

For example:
```
Name=K-001&Name=D-100&CMD!Combine=OR
```

## TCP API Module
The TCP API Module has been deprecated and replaced by the Universal API which is available via AppControls, Websocket and BBV. Existing APIs continue to work, but no new APIs are added to the legacy API.

For more details, please refer to the AppControl and Websocket Feature sections of the documentation documentation or visit the developer documentation under https://github.com/caxperts/AppControls.