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 UniversalPlantViewer, use deep linking.

Deep linking API: Link from outside > UniversalPlantViewer > Link to outside

UniversalPlantViewer uses link files to store link information. Link files are loaded automatically when you open UniversalPlantViewer but you can also load them manually at any time via File management > Load a link file ().

Create a Link File

Link files are generated using Excel. The Excel file should contain the following rows:

Condition	Link	Name
Task=Piping	https://www.caxperts.com/	Homepage
Task=Structure	https://en.wikipedia.org/wiki/Structure	Wikipedia

• “Condition” can be any attribute. “*” can be used as a wildcard to select every object.
  For example: Task=*

• “Link” may be a URL or local path. All attributes can be used for conditions. Absolute and relative paths are supported (using the backslash “\”).
  Example of a local path: data\docs\Valve.pdf

• “Name” represents the text displayed in UPV for the link.

Links in Isometrics

UniversalPlantViewer 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:

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

Furthermore, you have the option to generate a double-sided ISO PDF and preview the 3D objects to be included.

Please note that links to objects in the 3D model will be lost.

Deep Linking

You can use deep links in documents like Word, websites, and emails to open UniversalPlantViewer and execute specific queries and commands.

Deep linking employs 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 _ (any character) and * (any number of characters) as wildcards.

Example:

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

This will look for the Nozzle 3 on the object K-001, select and fit it to the screen while greying out all other objects.

UPVSelected

By adding UPVSelected=true or UPVSelected=false you can limit your query to items that are currently selected / not selected in UniversalPlantViewer.

Example:

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

This example using Combine=Or adds all items with Name=D-100 to the current selection.

There are no error messages for broken links, for example due to a typo.

Building Deep Links with Excel

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

Enter your model URL or path and a column for attributes, values and commands you want to include:

Paths might not work if they contain special characters. Use an URL encoder for paths to ensure them being correct.

	A	B	C
1	Model URL	…	-
2	Attribute	Value	Commands
3	Name	D-100	CMD!Fit
4	Task	Piping	CMD!SetVisibility=false
5	Pipeline	S-1672	CMD!Select&CMD!IntelliClip=1
6	Task	*	CMD!SetCameraView=3037!2476!72!180!180!10
7	…

Then add a function with the following structure:

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

Table 1: Commands

Command	Description
ClearClipping	Disables clipping
ClearColor	Restores the initial object colours.
ClearCustomAttributes	Reset all changes to custom attributes in this session.
ClearHighlight	Disables highlighting
ClearLinks	Removes LinkFile links
ClearSelection	Unselects all selected objects
Color	Color=[html color code] (format #RRGGBB or #RRGGBBAA) Example: CMD!Color=#FF0000
Combine	Combine=[OR/AND] Use “OR” if you want to use the operator “OR” between query conditions instead of “AND” (default).
ExportPackageFile	Exports package-files to the specified path.
Fit	Optional parameters: Centred. true (standard): fit to centre of the box. false: fit to the screen borders of the current view. Example: CMD!Fit=true
Highlight	Highlights the specified object Example: Name=D-100&CMD!Highlight
IntelliClip	IntelliClip=[distance in meters] Values >0 will display only the object. 0 will also display objects touching the selected object. You can use values with a decimal point.
LoadColorFile	LoadColorFile=[online or offline location] local: CMD!LoadColorFile=C:\colors.xlsx via http: CMD! LoadColorFile=http://sdfsdf.sdfsd.sdfsd …. via UNC: CMD!LoadColorF ile=file://////server/share/colors.xlsx Note: For UNC it is important to use 6 slashes “//////” after “file”. Examples: CMD!LoadColorFile=c:\colors.xlsx CM D!LoadColorFile=http://demo.universalpl antviewer.com/demoPlant/4/0/colors.xlsx
LoadConfigFile	Loads a configuration file. Parameters: Configuration file name Combine mode (optional). Sets handling of existing settings. By default set-tings are cleared: Merge (existing views will be merged and not cleared. Overrides existing values with the values of the configuration file) Example: C:/config.upv!Merge
LoadLinkFile	LoadLinkFile=[online or offline location] local:CMD!LoadColorFile=C:\colors.xlsx via http: CMD! LoadColorFile=http://sdfsdf.sdfsd.sdfsd … via UNC: CMD!LoadColorFile=file://////server/share/colors.xlsx Note: For UNC it is important to use 6 slashes “//////” after “file”.
LoadPackageFile	Loads package files from a specified path. Parameters: URL Replace (optional) If set true, replaces current packages instead of adding them to existing ones. Example: CMD!LoadPackageFile=c:\package.upvf!true
LoadSketch	Loads a sketch from the specified path. A second parameter renames the sketch. Example: CMD!LoadSketch=C:\Sketch\SketchFile.upvsk!NewName
ResetView	Resets the camera mode, the camera’s position, its rotation and states like highlights to how it was when the model was loaded.
SearchFallback	This command automatically adds the search string to the search box. If the exact search doesn’t return any results a fuzzy search will be started automatically. Example: upvapi://http://demo.universalplantviewer.com/demoPlant/4/0?Name=E240&NozzleName=N8&CMD!Select&CMD!Fit&CMD!Searchfallback This will start a search an find the Nozzle N8 of the equipment E-240
Select	Selects the specified object Example: Name=D-100&CMD!Select
SetCameraView	SetCameraView= [X!Y!Z!rotationX!rotationY!rotationZ] (Euler angle) Example: CMD!SetCameraView=3037!2476!72!180!180!90 sets the camera to the coordinates 3037 (X), 2476 (Y), 72 (Z = height) facing parallel to the ground rotated 90° to the left.
SetCameraViewLookAtTarget	SetCameraViewLookAtTarget=[X!Y!Z!TargetX!TargetY!TargetZ] Moves the camera to the specified location lets it face the target location.
SetClippingPlane	Sets the visible Camera-view-distance. The first parameter is the minimal distance of viewable objects, the second is the maximum distance. Example: CMD!SetClippingPlane=20!30
SetTreeConfiguration	SetTreeConfiguration=[discipline!discipline…] Example: CMD!SetTreeConfiguration=Task!SystemPath
SetVisibility	SetVisibility=[True/False]
SetVisibleAspects	SetVisibleAspects=[aspect!aspect]| Example: CMD!SetVisibleAspects=Simple Physical! Insulation to show both insulation and simple physical.
ShowOnly	Sets the visibility of all query objects to visible and hides all other objects.
ShowMessage	Shows a message and title in a messagebox. Example: CMD!ShowMessage=Your Message!Your Title
TakeAndSaveScreenshot	Takes a screenshot with the following parameters in order: Path where the image is to be stored Width in pixel Height in pixel Field of view in degree (above 160 might produce wrong images) Format, either .png or .jpg Hide UI, true or false Enable antialiasing, 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
VolumeClip	VolumeClip=[distance in meters] Values < 0 will be treated as 0. You can use values with a decimal point.
VolumeClipByCoordinates	Runs the volume clip algorithm with a bounding box defined by the parameters: X min Y min Z min X max Y max Z max Example: CMD! VolumeClipByCoord inates=-10.0!-10.0!-10.0!20.0!20.0!20.0

Wildcards:

• * = any character

• _ = any single character

Condition Operators

By default, query conditions are combined with 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

API Module

With the UniversalPlantViewer API external applications can send queries via URI or TCP to UniversalPlantViewer. You can integrate UniversalPlantViewer in any software.

Using the API module requires an API licence.

Queries

You can use all deep linking commands with wildcards and additional commands.

Use the Combine command to switch between AND / OR. After starting UniversalPlantViewer AND is the default value but it will not return to that automatically.

Table 2: TCP commands

Commands	Description
GetCameraView	Returns the current camera view.
GetClippingInfo	Returns coordinates of snapping-points and -lines of specified objects
GetModelInfo	Returns a dictionary describing all loaded models by Model URI List of all available attribute names List of all available aspect names.
GetObjects	Returns a list of all object UIDs.
GetObjectsAttributes	Returns a dictionary for each object containing its attributes. (Optional parameter: a list of attribute names). Example parameters: Name!Task
GetObjectsBoundingBox	Returns the bounding box for each object.
GetObjectsColors	Returns a dictionary for each object containing aspect name and default/current colour.
GetObjectSnapInfo	Returns coordinates of snapping-points and -lines of specified objects
GetSelectedObjects	Returns a list of all selected object UIDs
GetVisibleAspects	Returns all visible aspects
PlaceArc	Places an arc
PlacePly	Places a polygon

TCP commands and their parameters are defined in the UniversalPlantViewerApi.dll

Table 3: General TCP parameters

These parameters are located in the ParameterBase class and can be combined with every other command.

Parameter	Description
ClippingFilter	Limits the query to elements contained in specific clippings Corresponds to GetClippingInfo.
IntelliPidDrawingFilter	Limits the query to elements in specific IntelliPIDs.

Using JSON via TCP

The UniversalPlantViewer starts a TCP server (IP 127.0.0.1, listening to port 40123; the port can be changed via command line parameters) and can process simple JSON messages.

To start the communication, send the following initial message:

Field	Description	Type
Header	“UPVAPI1\n”	UTF-8 String

Table 4: Event callback registering

Command	Description	Example
AddEventCallback	Registers a new callback for the specified event name. The event callback has its RequestId set to the RequestId specified by the second parameter. Parameters: - Event name - RequestId (must not be used for other event callbacks)	SelectionChanged!1000
RemoveEventCallback	Unregisters a callback with the matching RequestId. Parameters: -RequestId	1000

Table 5: Events (TCP)

Command	Description	Example
LinkClicked	Is called after the user clicked an url link. By prefixing a link url with “event:” only the event is triggered without actually opening the link in the browser.	"LinkClicked": { "Url":"http://www.caxperts.com/", "Template": "http://www.caxperts.com", "AssociatedObject": "0001388c-0000-0000-8bf3-55d0615a1e10"}
SelectionChanged	Is called after the list of selected objects changed. Returns a list with the UIDs of objects in the new selection.	"SelectionChanged":["00004e23-0000-0000-0080c0fc06552004"]
PointerClicked	Is called after the user clicked somewhere in the model. Returns a dictionary with the position of the click within the window and the mouse button that was pressed. The mouse position origin is at the bottom left. Possible mouse button names: - Left - Middle - Right	"PointerClicked": {"Button": "Right", "X": 323, "Y": 549}

Table 6: Message protocol definition

Field	Description	Type
Message length	The number of bytes in the message.	Unsigned Integer (4 Byte) in Network Byte Order
Message	The JSON text	UTF-8 String

Table 7: JSON request definition

Field	Description	Type
Model	The URL of the model. Commands will be executed for this model only. If missing, commands will be executed for all models.	String
Condition	The object request in query syntax.	String
ConditionCombineMode	Sets the combine mode for querieswith several conditions. If not specified or set to AND, the conditions will be combined using AND. If set to OR, the conditions will be combined using OR.	String
Command	The command to beexecuted.	String
RequestId	A unique number that allows linking answers to requests. If not specified, “-1” is assumed.	Integer
CommandParameters	Used to set command parameters.	List of String, Integer and Floats.

JSON Example:

{
    "Model" : http://demo.universalplnatviewer.com/DemoPlant/3/",
    "Condition" : "Task=Equipment",
    "Command" : "Fit",
    "RequestId" : "1000",
    "ConditionCombineMode" : "OR",
    "CommandParameters" : \[ "True" \]
}

Table 8: JSON response

Field	Description	Type
ErrorCode	Contains the error code (0 = no error)	Integer
ErrorMessage	Contains the error description (empty = no error)	String
RequestId	Contains the RequestId that was transmitted in the query (-1 = standard, none transmitted)	Integer
ResultData	Contains the result of Get commands	Dictionary <String, Object>
Object depends on the Get command.

Example:

{
    "ErrorCode" : 0,
    "ErrorMessage" : "OK",
    "RequestId" : -775527921,
    "ResultData" : {
    }
}