Functions
Project
int	setProjectNumber (string s, bool overwriteExisting=false)

int	setProjectShortDescription (string s, bool overwriteExisting=false)

int	setProjectLongDescription (string s, bool overwriteExisting=false)

void	setTempValue (string name, var value)

var	getTempValue (string name)

array< string >	getListOfTempValues ()

void	clearListOfTempValues ()

Models
string	getModelByElement (string id, string domainFilter="all")

array< string >	getModelListByName (string name, string domain="geometry")

array< string >	getModelListByDomain (string domainFilter="all")

string	getRootNodeByModel (string modelID)

array< string >	getRootNodeListByDomain (string domainFilter="all")

array< string >	getRootContainerList (string modelName)

string	createModel (string name, bool createRootContainer=true, string domain="geometry")

object	getModelMetaData (string modelID)

int	deleteModel (string id)

bool	hasModel (string modelID)

var	getModelImportSettings (string modelID)

var	isModelReadOnly (string modelID)

var	removeModelReadOnly (string modelID)

Objects / Lookup
array< string >	getAllElements (string domainFilter="geometry")

bool	hasElement (string id)

array< string >	filterByProperty (array< string > inputList, string propertyName, string propertyDatatype, string filterPattern, bool checkInherited=true, string domains="geometry")

array< string >	filterByStatus (array< string > inputList, string status, bool value=true, string domains="geometry")

string	findContainerByName (string parentId, string name, string lookupDomain="all")

bool	isContainer (string id)

Object Manipulation
int	startProjectTransaction (string domain="geometry")

int	endProjectTransaction (string domain="geometry")

var	createObject (string parentID, object objectMap)

string	createObjectFromXml (string parentId, string objectXML)

int	deleteObjects (string idList)

object	getAsJSON (string objId)

int	setAsComposite (string id, bool composite)

Object Links
int	setLinkedObjects (string elementID, string IDList)

int	removeAllLinkedObjects (string id)

int	removeLinkedObjects (string id, string linkedIdList)

int	updateRuleBasedLinks (string domainName, bool visibleOnly=false)

int	removeRuleBasedLinks (string domainName)

Object Tooltips
array< string >	getListOfObjTooltips ()

void	addObjectListToTooltip (string idList, string tooltipname)

void	removeObjectListFromTooltip (string idList, string tooltipname)

Property Types
int	createPropertyType (string propName, string propDatatype, string uomCode, bool isInh, int target, string domainName="all")

int	setPropertyTypeMetaData (string pName, string ptype, object metadata)

int	deletePropertyType (string propertyName, string propertyDatatype, string domainName="all")

array< var >	getPropertyTypeBookmarkList ()

object	getPropertyTypeBookmark (string name)

object	getPropertyTypeBookmarkByID (string id)

int	activatePropertyTypeBookmark (string bookmark)

bool	setPropertyTypeActive (string pName, string ptype, string domain, bool active)

int	setAllPropertyTypesActive ()

bool	removePropertyTypeBookmark (string name)

int	removePropertyTypeBookmarkByID (string id)

string	addPropertyTypeBookmark (object bookmarkData)

Properties
int	setPropertyValue (string objId, string propName, string propDataType, var value)

int	deleteProperty (string objId, string propName, string propDatatype)

array< var >	getPropertyValues (string propName, string propDatatype, int maxValues=0, string domainName="all", bool getNullValues=false)

array< var >	getPropertyValuesByObjectList (string propertyName, string propertyDatatype, bool checkInherited, var objectIdList, int maxValues=0, string domains="all", bool getNullValues=false)

object	getPropertyListAsJSON (object options)

void	setPropertyListAsJSON (object propmap, object opt)

Property Scripts
object	getPropertyScriptList () const

string	getPropertyScriptCode (string domain, string pname, string datatype) const

string	getPropertyScriptFgColor (string domain, string pname, string datatype) const

string	getPropertyScriptBgColor (string domain, string pname, string datatype) const

int	setPropertyScriptCode (string domain, string pname, string datatype, string code)

int	setPropertyScriptFgColor (string domain, string pname, string datatype, string code)

int	setPropertyScriptBgColor (string domain, string pname, string datatype, string code)

object	addPropertyScript (string domain, string pname, string datatype, string code=string())

int	removePropertyScript (string domain, string pname, string datatype)

void	propertyScriptClearCache (string domain="all", string pname="", string datatype="")

object	getPropertyScriptOptions (string domain, string pname, string datatype)

int	setPropertyScriptOptions (string domain, string pname, string datatype, object opt)

Documents
int	synchronizeDocumentContainer (string containerId, bool waitForCompletion=false)

void	resetDocumentMetaData (string objId)

array< object >	findDocumentsByLocationGps (double lat, double lon, double distance, array< string > idList=array< string >())

array< object >	findDocumentsByLocationRangeGps (array< string > gpsCoordinates, double distance, array< string > idList=array< string >())

array< object >	findDocumentsByLocationGk (double rw, double hw, double distance, array< string > idList=array< string >())

array< string >	findDocumentsByDate (date start, date end, array< string > idList=array< string >(), bool useRef=false)

Activities - Calendar
string	createCalendar (string name, string comment)

int	removeCalendar (string calendarID)

array< string >	getCalendarList ()

string	getCalendarByName (string name)

string	getDefaultCalendar ()

string	getCalendarByTask (string taskID, bool checkInh=true)

int	setCalendar (string taskID, string calendarID)

int	removeCalendarFromTask (string taskID)

int	setCalendarOptions (string calendarID, object options)

object	getCalendarOptions (string calendarID)

array< object >	getCalendarExceptions (string calendarID)

int	addCalendarExceptions (string calendarID, array< object > exceptions)

int	removeCalendarException (string calendarID, var date)

int	clearCalendarExceptions (string calendarID)

int	setCalendarWorkingTime (string calendarID, object workingTime)

object	getCalendarWorkingTime (string calendarID)

int	calcWorkInMinutes (date start, date finish, string calendarID=string())

Activities - Task Restrictions
array< string >	getTaskRestrictionsList ()

string	getTaskRestrictionsByName (string name)

int	setTaskRestrictions (string taskID, string restrictionsID)

int	removeTaskRestrictions (string taskID)

Activities - Task Visualisations
object	getVisualisationList ()

int	setVisualisationByID (string taskIDList, string visID)

int	removeVisualisation (string taskIDList)

Activities - Tools
int	setTaskMode (string taskID, int mode)

int	recalculateActivityProject (string taskID=string(), bool visibleOnly=false)

object	calcPropertyValuesOverTime (string propName, string propType, object options)

int	createTimeSchedule (object config)

Geometry
int	hasContact (string objId1, string objId2, object options=object())

string	createContactObject (string parentId, string objId1, string objId2, string matId, object options=object())

array< string >	cutObject (string parentId, string objId, object plane=object(), bool closeCuts=true, bool splitUnconnectedParts=true)

string	mergeObjects (string parentContainerId, var idList, bool skipClosed=false, bool keepTransparency=false, bool keepCommonProperties=false, bool replaceParent=false)

bool	isIncludedIn (string objId1, string objId2)

int	isPointIncludedIn (double x, double y, double z, string objId, double tol=1.e-5)

int	checkIntersection (string objId1, string objId2)

int	transformObject (string objId, string transformation)

int	setAsOpening (string objId, string openingIDList)

string	getProjectionAsSvg (var idList, object options=object())

double	calcDistance (string objId1, string objId2)

var	calculateDistance (string meshID1, string meshID2)

int	swapOrientationOfTriangles (array< object > idList)

Geometry - Materials
array< string >	getMaterialList ()

var	addMaterial (string modelID, var materialData)

var	setMaterialData (string materialID, var materialData)

var	getMaterialData (string materialID)

var	removeMaterial (string materialID)

bool	hasMaterial (string materialID)

string	getMaterialIDByName (string matName)

Geometry - Color Scheme
array< string >	getColorSchemeList ()

var	addColorScheme (var colorSchemeData)

var	removeColorScheme (string colorSchemeID)

bool	hasColorScheme (string colorSchemeID)

var	setColorSchemeData (string colorSchemeID, var colorSchemeData)

var	getColorSchemeData (string colorSchemeID)

var	removeElementsFromColorScheme (string colorSchemeID, array< string > elementIDs)

var	removeAllElementsFromColorScheme (string colorSchemeID)

var	getColorItemsFromColorScheme (string colorSchemeID)

var	setActiveColorScheme (string colorSchemeID)

string	getActiveColorScheme ()

var	addColorItem (string colorSchemeID, var colorItemData)

var	removeColorItem (string colorItemID)

bool	hasColorItem (string colorItemID)

var	setColorItemData (string colorItemID, var colorItemData)

var	getColorItemData (string colorItemID)

var	addElementsToColorItem (string colorItemID, array< string > elementIDs)

var	getElementsFromColorItem (string colorItemID)

Geometry - Bounding Box
double	getBBoxMinX ()

double	getBBoxMaxX ()

double	getBBoxMinY ()

double	getBBoxMaxY ()

double	getBBoxMinZ ()

double	getBBoxMaxZ ()

int	calcOOBB (var objectIds, double eps=0.001)

int	updateOOBB (var objectIds, double eps=0.001)

int	calcOOBBxy (var objectIds, double eps=0.001)

int	updateOOBBxy (var objectIds, double eps=0.001)

object	getBoundingBoxCommon (var objectIds)

object	getOOBBCommon (var objectIds)

object	getOOBBxyCommon (var objectIds)

double	checkOverlapOBB (string id1, string id2, double eps=0.001)

Selection Sets
string	createSelectionSets (string propertyTypes, string rootName, object config=object())

array< string >	getRootNodeListSelectionSets (string domainFilter="all")

int	addToSelectionSetGeometry (string setId, string objectIDList)

int	removeFromSelectionSetGeometry (string setId, string objectIDs)

string	createSelectionSet (string name, string parentID=string())

bool	removeSelectionSet (string selsetID)

int	updateSmartSets (array< string > smartSetIDs=array< string >())

Regions of Alignments
string	addRegionToAlignment (string alignmentId, object setting)

int	removeAllRegionsFromAlignment (string alignmentId)

int	addRangeToRegion (string regionId, double fromStation, double toStation, string alignmentId=string())

int	removeRangeFromRegion (string regionId, double fromStation, double toStation, string alignmentId=string())

int	removeAllRangesFromRegion (string regionId, string alignmentId=string())

File Operations
int	createDirectory (string path, string dirName)

bool	writeFile (string filePath, string content, string encoding=string())

bool	appendToFile (string filePath, string content, string encoding=string())

bool	removeFile (string filePath)

bool	copyFile (string fnFrom, string fnTo)

bool	moveFile (string fnFrom, string fnTo)

bool	checkIfFileExists (string filePath)

bool	openFile (string filePath, string encoding=string())

bool	writeToFile (string content)

bool	closeFile ()

array< string >	readTextFile (string filename, bool ignoreLineBreakesInDoubleQuotes=false, string encoding=string())

string	readTextFileAsString (string filePath, string encoding=string())

var	readFileInChunks (string filePath, object options)

object	readCsvFile (string filePath, string delimiter=";", string encoding="Windows-1252")

int	csvOpen (string filePath, string delimiter=";", string encoding="Windows-1252")

array< string >	csvNextLine ()

bool	csvHasNextLine ()

bool	csvClose ()

string	readImageFile (string filename, string targetFormat="", bool applyExifRotation=false)

array< object >	getDirectoryEntryList (string dirPath, bool filesOnly=false, string orderBy="Name")

Database
bool	dbIsLocalCopy ()

string	dbGetFilepath () const

int	dbOpen (const var connectionData=var())

bool	dbClose ()

void	dbCheckIn ()

void	dbCheckOut (array< string > propList)

bool	dbQueryExec (string sqlQuery)

object	dbQueryRecordset (string sqlQuery, string key, int maxNumberOfRows=0)

bool	dbEndQueryExec ()

bool	dbQueryNext ()

var	dbQueryValue (int column)

string	dbQueryLastError ()

int	setPropertyValueDB (string objIdList, string propName, string propDataType, string propDomain, var value, bool createType=true)

int	writePropertyValueDB (string objIdList, string propName, string propDataType, string propDomain, var value, bool createType=true)

bool	startTransaction ()

bool	endTransaction ()

bool	dbGetImmediateUpdate ()

void	dbSetImmediateUpdate (bool)

int	dbClearCache (string propName, string propType)

void	dbClearCacheAll ()

int	dbDeleteProperty (string objIdList, string propName, string propType)

int	dbAssertTable (string tableName, array< string > columnsList)

Model Check / Clash Detection
bool	setCheckActive (string checkRunID, bool active)

var	getCheckActive (string checkRunID) const

int	runCheck (string checkRunID)

int	clearCheckResults (string checkRunID)

int	setCheckOptions (string checkRunID, object options)

object	getCheckOptions (string checkRunID) const

bool	setClashRunSettings (string clashRunID, var settings)

var	getClashRunSettings (string clashRunID) const

int	setCheckFilterList (string checkRunID, array< object > filterList, bool rightSet=false)

array< object >	getCheckFilterList (string checkRunID, bool rightSet=false) const

int	setCheckItems (string checkRunID, array< string > elementIDist, bool rightSet=false)

array< string >	getCheckItems (string checkRunID, bool rightSet=false) const

int	setPostProcessingCode (string checkRunID, string code)

string	addCheckRule (string checkRunID, object rule, string parentRuleID=string())

int	removeCheckRule (string checkRunID, string type, string ruleID)

int	clearCheckRules (string checkRunID, string ruleTypeFilter=string())

object	getCheckRules (string checkRunID, string ruleTypeFilter=string())

Geo Location
void	enableGeoLocation (int msecInterval=60)

void	disableGeoLocation ()

object	currentGeoPosition ()

Tools / Miscellaneous
int	setBoQBreakdownStructure (string boqModelID, string templateStr)

int	sortContainerByProperty (string containerId, string propName, string propType, bool ascending=true, int maxDepth=0)

int	validateIfcCompatibiliy (string bsModelID)

Functions inherited from CoreAPI
string	addDays (string dateStr, int nrDays)

int	getCalendarWeek (date dt)

string	createID ()

long	calcHashcode (string str)

string	compressToIfcGuid (string id)

string	uncompressFromIfcGuid (string ifcGuid)

bool	checkRegExp (string value, string pattern)

double	calcSlantedArea (string objId, double angleMin=0.0, double angleMax=45.0)

object	calcGpsCoordsByStation (string objId, double station)

object	calcGpsCoordsByModelCoords (double x, double y)

object	calcModelCoordsByGpsCoords (double lat, double lon)

object	calcGkCoordsByModelCoords (double x, double y, double z)

object	calcModelCoordsByGkCoords (double r, double h)

object	calcGkCoordsByGpsCoords (double lat, double lon)

object	calcGpsCoordsByGkCoords (double rw, double hw)

object	convertCoordinates (object coordinates)

string	idListToStr (array< string > idList)

array< string >	strToIdList (string strIDList)

var	mapToExternalIDs (const array< string > cpIDs)

var	mapFromExternalIDs (const array< string > cpExternalIDs)

var	getFileInfo (string filePath)

string	getAbsolutePath (string filePath)

string	getBaseName (string filePath)

string	getFileName (string filePath)

string	getApplicationDirectory ()

string	getApplicationFilename ()

string	getApplicationLanguage ()

string	getVersionAsString ()

object	getVersion ()

bool	requireVersion (int major, int minor, int patch)

string	getDomainByElement (string objId)

string	getUserName ()

string	getProjectName ()

string	getProjectDirectory ()

object	getProjectLocation () const

object	getProjectInfo ()

array< string >	getContainedElements (string containerId, int maxDepth, bool loadExternal=true)

int	countContainedElements (string containerId, int maxDepth, bool loadExternal=true)

string	getParent (string objId)

array< string >	getOpenings (string objId)

array< string >	getParts (string objId)

array< string >	getLinkedObjects (string objectIDList, string resultDomains="all", string objectLookupDomains="all")

bool	isVisible (string objId)

bool	isSelected (string objId)

var	getPropertyValue (string objId, string propName, string propType, bool inh=true)

array< object >	getPropertyValuesByObject (string objId, string filterpattern="*")

var	getPropertySource (string objId, string propName, string propType, bool inh=true)

string	getPropertyUnit (string propName, string propType)

object	getPropertyTypeMetaData (string propName, string propType)

array< object >	getPropertyTypeList (string domain="all", string filterPattern="*", bool activeOnly=false)

array< object >	getPropertyTypeListByObject (string objId, string filterPattern="*")

bool	isPropertyInherited (string objId, string propName, string propType)

string	getPropertyValueRange (string idList, string propName, string propType, string domainFilter="geometry")

var	evaluateFormula (string code, string id, string id_otherdomain=string())

string	prepareJsCode (string code, string id, int dec=-1, string frmt="%L1", int fieldWidth=10, QChar fillChar=QChar())

array< string >	extractPropertyNames (string code, string startTag="[[", string endTag="]]")

array< object >	getGlobalProjectProperties ()

array< object >	getPointList (string objId)

object	getPointOnAlignmentAtStation (string alignmentId, double d)

double	getStationOfProjectedPoint (string alignmentId, double x, double y, double z=0.0)

array< string >	getRegionsOfAlignment (string alignmentId)

array< object >	getRangesOfRegion (string alignmentID, string regionID)

double	getValueOfAlignmentRegion (string alignmentID, string regionID)

int	getTaskMode (string taskID)

string	getTaskVisualisation (string taskID)

string	getTaskRestrictionsByTask (string taskID)

Signals
void	synchronizationFinished (bool success)

void	fileChunkReceived (string data)

void	geoPositionUpdated (object pos)

Function Documentation

◆ activatePropertyTypeBookmark

int activatePropertyTypeBookmark ( string bookmark )

function

Activates a given property type bookmark and returns '1' on success and '-1' on failure.

Since: 2.2.4, 27 oct 2018; 3.5.0, 12 mar 2025 Allow bookmark activation by name.

Parameters

bookmark Name or ID of the bookmark.

Deprecated:: The ID parameter is deprecated and will be removed in future updates. Always refer to bookmarks by name in new scripts.

◆ addCalendarExceptions

int addCalendarExceptions	(	string	calendarID,
		array< object >	exceptions
	)

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Set exceptions (user defined days or holidays) to calendar. Existing dates will be overwritten.

Parameters

calendarID	ID of the calendar
exceptions	List of exceptions

See also: array< object > getCalendarExceptions(string calendarID)

Since: 2.9.2, 03 Mar 2022; 3.4.2, 10 May 2024 : deprecated

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

◆ addCheckRule

string addCheckRule	(	string	checkRunID,
		object	rule,
		string	parentRuleID = `string()`
	)

function

Add rule to check run. Only Attribute Rules can be nested.

Parameters

checkRunID	ID of (model) check run
rule	Object which defines the check rule. For rules of type 'AttributeRule', valid sub-types are 'simple' (no child rules allowed), 'conditional' and 'group'.
parentRuleID	ID of parent rule (attribute rule groups and conditional rules only)

Returns: ID (type 'AttributeRule' and 'ScriptRule') or empty string (UniquePattern)

Since: 2.9.3, 24 Mar 2022

Example:

var checkRunID = '0e40e665-a342-4948-b592-c95a6c6beca3';
var rule1 = {
    "Type": "UniquePattern",
    "Pattern": "[[cpID##xs:ID]]",
    "Comment": "Check uniqueness of GUIDs"
    };
desiteAPI.addCheckRule(checkRunID, rule1);
var rule2 = {
    "Type": "ScriptRule",
    "Name": "newRule",
    "Comment": "",
    "IsActive": true,
    "ResumeOnError": false,
    "Code": "// write some code here"
    };
desiteAPI.addCheckRule(checkRunID, rule2);
var rule3 = {
    "Type": "AttributeRule",
    "SubType": "conditional",
    "PropertyTypeKey": "ifcType##xs:string",
    "Pattern": "IfcSpace"
    };
var rule4 = {
    "Type": "AttributeRule",
    "SubType": "simple",
    "PropertyTypeKey": "Pset_SpaceCommon:IsExternal##xs:boolean",
    "Pattern": "*"
    };
var ruleID = desiteAPI.addCheckRule(checkRunID, rule3);
desiteAPI.addCheckRule(checkRunID, rule4, ruleID);

◆ addColorItem

var addColorItem	(	string	colorSchemeID,
		var	colorItemData
	)

function

Create a new color item for the provided color scheme. This is only applicable to custom color schemes.

Parameters

colorSchemeID	color scheme ID to create the item for
colorItemData	color item data passed as an object

Example:

const colorSchemeID = "e221a15a-7f66-4c52-88ad-8e08e1e41ff9";
let result = desiteAPI.addColorItem(colorSchemeID,
{
    name: "Red",
    color: { r: 1, g: 0, b: 0, a: 0.3 },
    outline: true
});

Returns: result with error code 0 on success or > 0 on failure.
{
"error":
{
"code": 0,
"message": "OK"
},
"id": "19580e78-7028-4eac-aa60-68064053f82d" // ID of the new color item or empty in case of an error
}

Since: 3.5.0, 10 Apr 2024

◆ addColorScheme

var addColorScheme ( var colorSchemeData )

function

Create a new color scheme to apply temporary colors to geometric elements in the project.

Parameters

colorSchemeData color scheme data passed as an object

Example:

let result = desiteAPI.addColorScheme(
{
    name: "My Color Scheme",
    focused: true // This will fade out the remaining geometric elements in the project
});

Returns: result with error code 0 on success or > 0 on failure.
{
"error":
{
"code": 0,
"message": "OK"
},
"id": "19580e78-7028-4eac-aa60-68064053f82d" // ID of the new color scheme or empty in case of an error
}

Since: 3.5.0, 10 Apr 2024

◆ addElementsToColorItem

var addElementsToColorItem	(	string	colorItemID,
		array< string >	elementIDs
	)

function

Add geometric elements to a color item.

Parameters

colorItemID	ID of the color item
elementIDs	IDs of the geometric elements to add

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.5.0, 10 Apr 2024

◆ addMaterial

var addMaterial	(	string	modelID,
		var	materialData
	)

function

Create a new material to change the look of a geometric element in the project.

Parameters

modelID	ID of the model to assign the new material to. If empty, a default material will be created.
materialData	material data passed as an object

Example #1:

// Create a default material by passing no model ID.
const modelID = "";
let result = desiteAPI.addMaterial(modelID,
{
    name: "Red",
    ambient: { r: 0.75, g: 0, b: 0, a: 1 },
    diffuse: { r: 0.75, g: 0, b: 0, a: 1 },
    specular: { r: 1, g: 1, b: 1, a: 1 },
    transparency: 0.0,
    shininess: 0.5
});

Example #2:

// Create a material assigned to a model with a given model ID.
// These materials will be owned by the model and can only be deleted with the model.
const modelID = "380fcbc0-66b0-45c8-a4a9-dd2f3c74d438";
let result = desiteAPI.addMaterial(modelID,
{
    name: "White",
    ambient: { r: 1, g: 1, b: 1, a: 1 },
    diffuse: { r: 1, g: 1, b: 1, a: 1 },
    specular: { r: 1, g: 1, b: 1, a: 1 },
    transparency: 0.0,
    shininess: 0.5
});

Returns: result with error code 0 on success or > 0 on failure.
{
"error":
{
"code": 0,
"message": "OK"
},
"id": "19580e78-7028-4eac-aa60-68064053f82d" // ID of the new material or empty in case of an error
}

Since: 3.4.1, 08 Feb 2024

◆ addObjectListToTooltip

void addObjectListToTooltip	(	string	idList,
		string	tooltipname
	)

function

Add object list to tooltip.

Parameters

idList	List of objects
tooltipname	Name of the tooltip template

Since: 1.3.2, 28 mar 2014, jh

◆ addPropertyScript

object addPropertyScript	(	string	domain,
		string	pname,
		string	datatype,
		string	code = `string()`
	)

function

Since: 2.5.0, 10 mar 2019, jh

◆ addPropertyTypeBookmark

string addPropertyTypeBookmark ( object bookmarkData )

function

Add property type bookmark.

Parameters

bookmarkData The data for the new bookmark, look at getPropertyTypeBookmark() for a format description.

Returns: ID of new bookmark.

Since: 2.2.4, 27 oct 2018

Deprecated:: The ID parameter is deprecated and will be removed in future updates. Always refer to bookmarks by name in new scripts.

◆ addRangeToRegion

int addRangeToRegion	(	string	regionId,
		double	fromStation,
		double	toStation,
		string	alignmentId = `string()`
	)

function

Add an ADDITIONAL range to a region (a region can have several - possibly disjunct - ranges with the same value).

Parameters

regionId	ID of region (will be returned if region is successfully added to an alignment)
fromStation	Lower bound of range
toStation	Upper bound of range
alignmentId	ID of alignment. Optional parameter, if given, method is faster, because not all objects have to be searched

Returns: 1 success
-1 alignment ID not found
-2 region ID not found
-3 invalid range parameters

Since: 2.2.1, 20 apr 2018, sl

◆ addRegionToAlignment

string addRegionToAlignment	(	string	alignmentId,
		object	setting
	)

function

Add a region with a first given range and value to an alignment (simplified, linear representation of a road or track).
A region is represented by a strip along an alignment with a name, value and color and is used to visualize different properties/data, indicated by a color and a value, along the alignment. Further ranges (which will get the same name, color and value) can be added to this region afterwards. At the beginning of each range, the name and the value set will be drawn (like stations).

Parameters

alignmentId	ID of alignment
options	Options, given as json object (see below).

See also: addRangeToRegion()

Example

var options =
{
    name:      'Test',
    range:     [100.0,126.5],
    value:     123.456,
    offset:    2.0,
    offsetZ:   0.0,
    width:     1.0,
    color:     '#ff00cc',
    textcolor: '#000000',
    textscale: 0.5
}

Returns: ID of region created
-1 alignment ID not found
-3 invalid settings
-4 region range outside range of alignment

Since: 2.2.1, 26 apr 2018, sl

◆ addToSelectionSetGeometry

int addToSelectionSetGeometry	(	string	setId,
		string	objectIDList
	)

function

Add objects to selection set in domain 'geometry'.

Returns: 1 Ok
-1 Selection Set not found in domain 'geometry' -2 Object not found in domain 'geometry'

Since: 2.2.2, 28 aug 2018, jh

◆ appendToFile

bool appendToFile	(	string	filePath,
		string	content,
		string	encoding = `string()`
	)

function

Append a string to a file. User does not need to take care of opening and closing the file.

Parameters

filePath	Name and path of the file to be written. If no path is given, the current project's path will be used.
content	Data to be appended to the end of the file
encoding	File encoding, such as "ISO 8859-1", "UTF-8", or "UTF-16". To write binary data, use "base64" and encode the string accordingly.

Returns: true if file was written successfully, else false

Since: 2.0.16, 27 Oct 2017; 2.4.2, 01 Mar 2019 : changed behavior when no path is given (using project directory instead of application directory); 2.9.0, 06 Dec 2021 : added binary writing mode of base64 encoded data

◆ calcDistance

double calcDistance	(	string	objId1,
		string	objId2
	)

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Calculate distance between two mesh objects.

Parameters

objId1	ID of first object
objId2	ID of second object

Returns: Distance, if no error occurred. If objects intersect, distance is zero.
-1 Could not find objects/wrong type.

Since: 2.2.2, 31 Aug 2018; 3.2.2, 11 Apr 2023 : deprecated

Deprecated:: Use calculateDistance() instead.

◆ calcOOBB

int calcOOBB	(	var	objectIds,
		double	eps = `0.001`
	)

function

Calculate optimized, orientated bounding box (OOBB) of all given geometric objects and set it to them. The bounding box is only calculated and set if an object has no OOBB yet.

Parameters

objectIds	IDs of objects to be affected (array or string, using ';' as separator)
eps	Threshold for optimization (default: 0.001)

Returns: Number of affected objects

Since: 1.5.0, 13 Jan 2015; 2.1.5, 19 Jan 2019 : extended to handle composites; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ calcOOBBxy

int calcOOBBxy	(	var	objectIds,
		double	eps = `0.001`
	)

function

Calculate optimized, orientated bounding box in xy-plane (OOBBxy) of all given geometric objects and set it to them. The bounding box is only calculated and set if an object has no OOBBxy yet.

Parameters

objectIds	IDs of objects to be affected (array or string, using ';' as separator)
eps	Threshold for optimization (default: 0.001)

Returns: Number of affected objects

Since: 1.5.0, 13 Jan 2015; 2.1.5, 19 Jan 2019 : extended to handle composites; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ calcPropertyValuesOverTime

object calcPropertyValuesOverTime	(	string	propName,
		string	propType,
		object	options
	)

function

Calculate property values over time. Returns an object with a list of property values for each day between startDay and endDay.

Options:

var options = {
    'StartDay':       '2018-09-10', // if invalid the current date is set
    'EndDay':         '2018-09-20', // if invalid the current date is set
    'VisibleTasks':   false,        // consider only visible tasks
    'CheckInherited': false,        // check inherited values
    'BaseIndex':      0             // 0 = Default, 1 = Actual, 2 = Baseline
};
var pv = desiteAPI.calcPropertyValuesOverTime( 'cpCost', 'xs:double', opt );

Return:

{
    "2018-09-10": 3.5,
    "2018-09-11": 3,
    "2018-09-12": 0,
    "2018-09-13": 0,
    "2018-09-14": 3,
    "2018-09-15": 0,
    "2018-09-16": 3,
    "2018-09-17": 3,
    "2018-09-18": 36,
    "2018-09-19": 3,
    "2018-09-20": 0
}

Since: 2.2.3, 14 Sep 2018

◆ calculateDistance

var calculateDistance	(	string	meshID1,
		string	meshID2
	)

function

Calculate distance between two mesh objects.

Parameters

meshID1	ID of first mesh
meshID2	ID of second mesh

Returns: Object containing error information, the calculated distance, and the points of closest approach of the two meshes.
Example:
{
"closestPoints": [
{
"x": 18.747232434082033,
"y": 13.39334411315918,
"z": 3.000000022888184
},
{
"x": 18.747232434082033,
"y": 13.39334411315918,
"z": 6.000000045776368
}
],
"distance": 3.000000022888184,
"error": {
"code": 0,
"message": "OK"
}
}

On error (e.g. if one of the two input IDs could not be found or is not a mesh), "closestPoints" and "distance" will be missing from the output.
If the two meshes intersect, "distance" will be 0.0.

Since: 3.2.2, 11 Apr 2023

◆ calcWorkInMinutes

int calcWorkInMinutes	(	date	start,
		date	finish,
		string	calendarID = `string()`
	)

function

Calculate working time in minutes between two given dates by specifying a calendar.

Parameters

start	Start date and time
finish	Finish date and time
calendarID	ID of calendar (if empty the default calendar is used)

Returns: 1 Ok
-1 Invalid start or finish
-2 Could not find calendar

Since: 2.8.5, 14 Oct 2021

◆ checkIfFileExists

bool checkIfFileExists ( string filePath )

function

Checks if a file exists

Parameters

filePath Name and path of the file. If no path is given, the current project's path will be used.

Returns: true if file exists, else false

Remarks: 2.4.2, 01 mar 2019, ah : changed behavior when no path is given (using project directory instead of application directory)

Since: 1.9.0, 05 jul 2016, mm

◆ checkIntersection

int checkIntersection	(	string	objId1,
		string	objId2
	)

function

Check if two geometric objects intersects.

Parameters

objId1	: ID of object #1
objId2	: ID of object #2

Returns: 1 Objects do intersect
0 Objects do not intersect
-1 No Object with given ID objId1 or objId2 or of wrong type

Since: 1.9.0, 13 Apr 2016; 3.5.0, 28 Oct 2024 : Removed tolerance - it can no longer be provided due to internal changes of how tolerances are applied to objects

◆ checkOverlapOBB

double checkOverlapOBB	(	string	id1,
		string	id2,
		double	eps = `0.001`
	)

function

Check overlap of oriented bounding boxes of two given objects. If an OOBB has not been already calculated for each object, it will be calculated with numerical precision eps (default 0.01).

Parameters

id1	ID of first object
id2	ID of second object
eps	Precision for generating missing OOBBs

Returns: A value between [0, 1] indicating the overlapping factor (of the smaller box).

Note: In case of two OBBs with the same orientation it is the exact percentage of overlap, else only a indicative value. If no geometric object exists for one of both IDs, 0.0 will be returned.

Since: 1.4.10, 01 jun 2015, sl

◆ clearCalendarExceptions

int clearCalendarExceptions ( string calendarID )

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Removes all exceptions from a calendar.

Parameters

calendarID ID of the calendar

Returns: 1 Ok
-1 Could not find calendar

Since: 2.9.2, 03 Mar 2022; 3.4.2, 10 May 2024 : deprecated

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

◆ clearCheckResults

int clearCheckResults ( string checkRunID )

function

Remove all check results from check.

Parameters

checkRunID ID of checkRun

Returns

1 Ok
-1 Check run with given id not found

Since: 2.9.0, 21 Sep 2021

◆ clearCheckRules

int clearCheckRules	(	string	checkRunID,
		string	ruleTypeFilter = `string()`
	)

function

Remove all check rules from check run.

Parameters

checkRunID	ID of (model) check run
ruleTypeFilter	Type of check rule. If empty, all check rules will be removed. "ScriptRule" "AttributeRule" "UniquePattern"

Returns

Error code

1 Ok
-1 Check run with given id not found
-2 Unknown rule type

Since: 2.9.3, 24 Mar 2022

◆ closeFile

bool closeFile ( )

function

Close an open file. There can only be one open file at once!

Returns: true - success
false - file is not open

Since: 1.3.0, 30 Oct 2013

◆ copyFile

bool copyFile	(	string	fnFrom,
		string	fnTo
	)

function

Copy file 'fnFrom' to file 'fnTo'.

Since: 2.0.18, 31 jan 2018, jh

◆ createCalendar

string createCalendar	(	string	name,
		string	comment
	)

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Create a new calendar.

Parameters

name	Name of calendar (should be unique, must not be empty)
comment	Comment

Returns: ID of calendar created.

Since: 2.9.2, 03 Mar 2022; 3.4.2, 10 May 2024 : deprecated

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

◆ createContactObject

string createContactObject	(	string	parentId,
		string	objId1,
		string	objId2,
		string	matId,
		object	options = `object()`
	)

function

Create contact object (contact surface) between two objects. If angle > 0, the resulting surface may differ for each object. In this case the projection on object 1 ist choosen.

Parameters

parentId	: ID of container the newly created object should be added.
objId1	: ID of object 1.
objId2	: ID of object 2.
matId	: ID of material of the newly created object. If empty, a default material (dark orange) will be chosen.
options	: Options encoded as JSON. If not specified, the default values of the code snipped (see below) will be chosen.

Returns: ID of new object, else "" if no contact could be calculated, or
-1 - error, object 'objId1' not found or of wrong type
-2 - error, object 'objId2' not found or of wrong type
-3 - error, Element 'parentId' not found or of wrong type
-4 - error, model not found or model is read-only

var opt = {
    locflag: 7,   // 1 = contact at top, 2 = contact at bottom, 4 = contact at sides (and combinations)
    tol: 0.001,   // maximum distance tolerance [m]
    oppdir: true, // flag that indicates that normal vectors of contacting faces must point in opposite directions
    angle: 2.0    // maximum angle deviation between normal vectors of opposite faces [�]
}
var idnew = desiteAPI.createContactObject( parentId, id1, id2, "", opt );

Since: 1.5.0, 07 Jan 2015

◆ createDirectory

int createDirectory	(	string	path,
		string	dirName
	)

function

Create new directory at given file path. Resulting directory path is path + '/' + dirName.

Parameters

dirName	Name of new directory
path	File path of directory in which new directory should be created (relative paths are allowed)

Returns: error code:
1 - success
0 - directory already exists, no changes
-1 - error -2 - execution blocked

Since: 1.5.0, 16 Mar 2016

◆ createModel

string createModel	(	string	name,
		bool	createRootContainer = `true`,
		string	domain = `"geometry"`
	)

function

Create a new model in a specified domain.

For models within the geometry domain, a root container has to be created.
To access the root node of the model use the function getRootNodeByModel().

Parameters

name	Name of the new model
createRootContainer	If true, create a root container with the same name as the new model (only relevant for domain 'geometry'; a root container is a container on which transformations can be applied)
domain	Domain in which the model is created

Returns: ID of new model.
-1 Model could not be created.
-2 Domain is unknown or not unique

Since: 1.3.0, 21 Jan 2014

◆ createObject

var createObject	(	string	parentID,
		object	objectMap
	)

function

Create an object encoded as a JavaScript object map.

Parameters

parentID	ID of parent container
objectMap	JavaScript object; see examples below

Returns: either ID of newly created object or one of the error codes listed below

Error Codes:

 0 : Undefined
-1 : Could not find parentId
-2 : parent is not a container or does not have the required type
-3 : could not find model of parentId
-4 : could not create new object
-5 : parsing Error
-10 : unsupported object type (tag name)

DOMAIN ISSUES

Available objects

container
issue
viewpoint

Examples

{"container": {"ID": "IdOfIssuesContainer", "name": "container-1"}}

{
    "issue": {
        "ID": "98f7ae3f-403a-413e-a3ae-e8b8b2a9fed7",
        "name": "issue-1",
        "description": "Some description.",
        "status": "Open",
        "assignedTo": "someone@thinkproject.com",
        "priority": "Normal",
        "due": "2021-11-25T12:00:00.000"
    }
}

The elements "description", "status", "assignedTo", "priority" and "due" are optional. If "status" or "priority" are omitted, default values will be set according to the project configuration.
If the project is configured to only allow a fixed set of values for Priority and/or Status, non-compliant values are replaced by defaults.
Any passed "ID" must be a valid GUID to be accepted as bcfID and cpExternalID.

{
    "viewpoint": {
        "ID": "950a65f2-3590-48ca-9e7b-0409063116ce",
        "camera": { ... },
        "clippingPlanes": [ ... ],
        ...
        }
}

See ProjectAPI::getViewpointData() for a full example of all the data fields.

Since: 1.0.17, 16 Jun 2012 : Originally introduced for creating empty attribute objects.; 2.9.0, 24 Nov 2021 : Re-implemented as a way to create objects from JS objects.; 3.5.0, 27 Jan 2025 : Behavior of "ID" key changed. If given, it will now be processed as cpExternalID. Check the function's return value for the cpID.

◆ createObjectFromXml

string createObjectFromXml	(	string	parentId,
		string	objectXML
	)

function

Create a new object encoded by XML.

Parameters

parentId	ID of parent element
objectXML	XML code

Returns: ID of new object, else
error code if object cannot be created.

Error Codes:

 0 : Undefined
-1 : Could not find parentId
-2 : parent is not a container, does not have the required type or is read-only
-3 : could not find model of parentId
-4 : could not create new object
-5 : parsing Error
-10 : unsupported object type (tag name)

DOMAIN GEOMETRY

Available objects

<object3D>
<objectLines>
<objectText>
<genericObject>
<container>
<objectPoint>

Examples

If the attribute "matID" is used, the material must exist in the same model as the object. If this attribute is not used, a default material will be created in the same model as the object.

<object3D ID="ABCxyz123" name="object-1" matID="19580e78-7028-4eac-aa60-68064053f82d" >
 <p nr="0" x="1.0" y="1.0" z="1.5" />
 <p nr="1" x="10.0" y="20.0" z="1.5" />
 <p nr="2" x="1.0" y="10.0" z="1.5" />
 <t p1="0" p2="1" p3="2" />
</object3D>

<objectLines ID="ABCxyz123" name="line-1">
 <color r="0.5" g="0.5" b="0.5" a="1.0" />
 <p nr="0" x="1.0" y="1.0" z="1.5" />
 <p nr="1" x="10.0" y="20.0" z="1.5" />
 <l p1="0" p2="1" />
</objectLines>

<objectText ID="ABCxyz123" name="text-1">
  <color r="0.5" g="0.5" b="0.5" a="1.0" />
  <textItem c="Der Text" h="1.0" rx="0.0" ry="0.0" rz="0.0" x="0.0" y="0.0" z="0.0"></textItem>
</objectText>

<container ID="IdOfContainer" name="container-1" />
// create composite
<container ID="idabc" name="c1" composite="true" />

<objectPoint ID="IdOfPoint" name="point-1">
  <p x="1.0" y="1.0" z="1.5" />
</objectPoint>

DOMAIN ACTIVITIES

Available objects

<task>

Note: If WBS is empty, it will be automatically created from parent task WBS and child index of the new task.

Examples

DOMAIN BUILDING STRUCTURE

Available objects

Available types:

typeBsUnknown
typeBsContainer
typeBsSection (general containment)
typeBsSite
typeBsBuilding
typeBsBuildingStorey
typeBsLevel (arbitrary level)
typeBsUnit (e.g. an apartment unit)
typeBsSpace (room)
typeBsLocation (any location point)
typeBsAlignment (e.g. road)
typeBsAlignmentHorizontal
typeBsAlignmentVertical
typeBsAlignmentCant
typeBsStation (station point of alignment)
typeBsSegment (e.g. line, curve or spiral)
typeBsTakt
typeBsGroup (group, zone, system)
typeBsFacility
typeBsFacilityPart
typeBsBridge
typeBsRailway
typeBsRoad
typeBsMarineFacility

Examples

Create two nested sections in the building structure

var objXml = '<section name="Building A" type="typeBsBuilding"/>';
var id = desiteAPI.createObjectFromXml( parentId, objXml );
objXml = '<section name="00EG" type="typeBsBuildingStorey"/>';
var id2 = desiteAPI.createObjectFromXml( id, objXml );

DOMAIN DOCUMENTS

Available objects

<document>
<documentDir>
<container>

Examples

<document ID="xyz123" path="C:/file.json" created="2016-03-16T12:27:34" createdBy="user" refDateTimeStart="" refDateTimeFinish="">
    <location refID="abc321" lon="45.55523" lat="7.04567" refFrom="" refTo="" />
</document>

Note that a "document" object can be used either as a file link or as a URL.
A "documentDir" will scan contained directories recursively, so deeply nested directory structures may incur a performance penalty.

DOMAIN BoQ (Bill of Quantities)

Available objects

<item>

Examples

<item wbs="1.1" ID="3" name="newItem" type="2">
   <attr>
     <qty>0</qty>
     <unit></unit>
     <up>0</up>
   </attr>
 </item>

Available types:
1 - Category (LV-Bereich)
2 - BOQ-Item (LV-Position)
3 - Markup Item (Zuschlagsposition)
4 - Remark (Hinweistext)
5 - Performance Description (Ausfuehrungsbeschreibung)
6 - Sub-Description (Unterbeschreibung)
7 - Invalid, reserved for internal use
8 - AddText (Zusatztext)
9 - Take-Off Sheet (Aufmassblatt)
10 - Take-Off Row (Aufmasszeile)

"qty" is the quantity as floating point number (double).
"unit" is the unit of measurements as text.
"up" is the unit price as a floating point number (double).

Example JavaScript:

var id = desiteAPI.createID();
var xml = '<item wbs="1.1" ID="' + id + '" name="Stahlbeton Decken" type="2"> \
    <attr> \
        <qty>10.123</qty> \
        <unit>m2</unit> \
        <up>0</up> \
    </attr> \
</item>';
var parentId = '32b098cf-6942-4abf-a9fc-81fe229db767';
var ret = desiteAPI.createObjectFromXml( parentId, xml );
ret;

DOMAIN TYPES

Available objects

Examples

"ID", "prefix" and "comment" are optional.

DOMAIN PROCESS COMPONENTS

Available objects

Examples

DOMAIN CLASH DETECTION

Available objects

<cdRun>

Examples

DOMAIN MODEL CHECK

Available objects

Examples

DOMAIN ISSUES

Available objects

<container>
<issue>
<viewpoint>

Examples

<issue ID="98f7ae3f-403a-413e-a3ae-e8b8b2a9fed7" name="issue-1">
    <description>Some description.</description>
    <status>Open</status>
    <assignedTo>someone@thinkproject.com</assignedTo>
    <priority>Normal</priority>
    <due>2021-11-25T12:00:00.000</due>
</issue>

The elements "description", "status", "assignedTo", "priority" and "due" are optional. If "status" or "priority" are omitted, default values will be set according to the project configuration.
If the project is configured to only allow a fixed set of values for Priority and/or Status, non-compliant values are replaced by defaults.
Any passed "ID" must be a valid GUID to be accepted as bcfID and cpExternalID.

<viewpoint ID="950a65f2-3590-48ca-9e7b-0409063116ce" name="API Demo">
    <camera>
        ...
    </camera>
    <clippingPlanes>
        ...
    </clippingPlanes>
    ...
</viewpoint>

See ProjectAPI::getViewpointData() for a full example of all the data fields, which then must be adapted into XML elements.
Prefer using createObject(), which accepts data in JavaScript object format rather than XML.

Since: 1.5.0, 06 Jul 2015; 2.0.8, 05 Jan 2017 : Added support for domain BoQ.; 2.1.0, 24 Apr 2017 : Added support for domain Types.; 2.2.1, 25 May 2018 : Added support for domain ProcessComponents.; 2.4.1, 31 Jan 2019 : Added support for containers in domain Documents.; 2.4.3, 28 May 2019 : Added support for types 9 and 10 in domain BoQ.; 2.5.4, 08 Feb 2020 : Added attribute "type" to "section" element in domain BuildingStructure.; 2.9.0, 24 Nov 2021 : Added support for domain Issues.; 3.4.0, 10 Jan 2024 : Removed support of "<objectProxy>" (domain Geometry).; 3.5.0, 10 Apr 2024 : Removed matID node from text, lines and points. Added color node to apply a custom color to text and lines.; 3.5.0, 27 Jan 2025 : Behavior of "ID" key changed. If given, it will now be processed as cpExternalID. Check the function's return value for the cpID.; 3.5.0, 25 Mar 2025 : Added support for IFC 4x3 Spatial Structure Types

◆ createPropertyType

int createPropertyType	(	string	propName,
		string	propDatatype,
		string	uomCode,
		bool	isInh,
		int	target,
		string	domainName = `"all"`
	)

function

Returns: 0 undefined
1 Property Type created
2 Property Type already exists
-1 Error, could not create Property Type
-2 Error, undefined target

Parameters

uomCode	Unit of Measurement
target	1 - Project Repository 2 - Database

Since: 2.0

◆ createSelectionSet

string createSelectionSet	(	string	name,
		string	parentID = `string()`
	)

function

Parameters

name	Name of new Selection Set
parentID	Parent of new Selection Set. If empty, the set is created on top level.

Since: 2.5.1, 30 Apr 2019

◆ createSelectionSets

string createSelectionSets	(	string	propertyTypes,
		string	rootName,
		object	config = `object()`
	)

function

Create selections sets of geometry objects.
For each value of a given property type a selection set is created.

Parameters

propertyTypes

A concatenation of Property Type Keys, each containing a name and datatype.
Example:

'cpName##xs:string;cpVolume##xs:double'

Prior to version 2.2.1, it was only possible to give a single property name, and the type was always String. Example: 'cpName'.
This is still possible, but deprecated.

Parameters

rootName Name of the Selection Set Container to be created. If the name is empty, the name is constructed from property type key names. If the name is already used, a suffix will be added.

config

Object/map containing options.

Default Values:
{
"maxItems" : 0,
"considerCompositeParts" : true,
"considerOpenings" : true,
"considerParts" : true,
"intervalSize" : 0.5,
"visibleOnly" : false,
"createAsSmartSet" : false
}
Note:
The option "visibleOnly":true only works for selection sets, not smart sets
If "maxItems" is greater the zero, this will define the maximum allowed nesting depth (used property types)

Usage examples:

desiteAPI.createSelectionSets('cpName', 'selSet1');                // deprecated!
desiteAPI.createSelectionSets('cpName##xs:string', 'selSet2'); // better! (since 2.2.1)
desiteAPI.createSelectionSets('cpName##xs:string; cpVolume##xs:double', 'selSet3', { intervalSize: 1.0 });

Returns: ID of new selection sets.
Empty string if selection set could not be created.

Since: 1.4.0; 2.2.1, 07 Aug 2018 : extended first parameter to support list of Property Type Keys; 2.8.4, 13 Aug 2021 : extended options to consider visible object only; 2.8.5, 11 Dec 2021 : extended options to create smart sets

◆ createTimeSchedule

int createTimeSchedule ( object config )

function

Create a time schedule from building structure and process components (Tools 4D).

Parameters

config

Calculation settings

{
    'pcRootID' : 'dab8cd58-e961-4419-87f8-d493261bd540',    // ID of process components root node
    'bsRootID' : '5c3abb0e-47b4-42e6-91a5-116a3eb38cc8-oh', // ID of building structure root node
    'calendarID' : '',                                      // ID of calendar (optional). If empty, the default calendar is used
    'projectStart' : '2022-01-03T08:00:00'                  // Project start date/time (ISO string or Date) (optional). If empty, the current date is used
}

Returns: 1 - Ok
0 - No Tools4D module
-1 - Error, could not find element 'pcRootID'
-2 - Error, could not find element 'bsRootID'
-3 - Error, could not find calendar
-4 - Error, invalid date/time

Since: 2.9.2, 18 Mar 2022

◆ csvClose

bool csvClose ( )

function

Finish/cleanup of reading a CSV file, started by csvOpen().

Returns: false if there's no active CSV file

Since: 2.2.4, 30 Oct 2018

◆ csvHasNextLine

bool csvHasNextLine ( )

function

Checks if CSV file opened by csvOpen() has another line of data.

See also: csvNextLine()

Returns: true if CSV file has another line of data.

Since: 2.2.4, 30 Oct 2018

◆ csvNextLine

array< string > csvNextLine ( )

function

Returns next line of a CSV file initialized by csvOpen().

Returns: cell data as array of strings (or empty array if no CSV file has been opened, or end of file reached)

See also: csvHasNextLine()

Since: 2.2.4, 30 Oct 2018

◆ csvOpen

int csvOpen	(	string	filePath,
		string	delimiter = `";"`,
		string	encoding = `"Windows-1252"`
	)

function

Open text file in CSV format for reading.

Parameters

filePath	Name and path of file (if path is missing, file is expected in the project directory)
delimiter	One character as delimiter of cells, most common are semicolon or tab.
encoding	File Encoding, by default "Windows-1252". Other options are "UTF-8", "UTF-16", "ISO 8859-1".

Returns: 1 - successful
-1 - invalid parameter (wrong length of delimiter or unrecognized encoding)
-2 - unused since 3.2.3 (treat like -1) -3 - file not found
-4 - error reading file
-5 - execution blocked

Since: 2.2.4, 30 Oct 2018; 2.4.5, 13 Aug 2019 : changed behavior when no path is given (using project directory instead of application directory); 3.2.3, 11 May 2023 : re-implemented to support multibyte characters, added optional encoding parameter

◆ currentGeoPosition

object currentGeoPosition ( )

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Returns the current geo position, this is the cached position signaled by geoPositionUpdated.
Location tracking has to be active, otherwise call desiteAPI.enableGeoLocation.

Returns: {
"Lat": 35.23028571362665,
"Lon": 37.6603185283756
}

Since: 2.9.0, 11 Oct 2021; 3.1.0, 04 May 2022 : moved from CoreAPI; 3.1.0, 27 Jun 2022 : deprecated

Deprecated:: The function is not useful when called immediately after enableGeoLocation(), as the sensor won't have any data yet.
Instead, connect to signal geoPositionUpdated.
If you only want a "one shot", you can disconnect immediately after having received the geo data:

desiteAPI.enableGeoLocation();
desiteAPI.geoPositionUpdated.connect(function onGeoPositionUpdated(pos)
{
    console.log('Latitude: ' + pos['Lat'] + ', Longitude: ' + pos['Lon']);
    desiteAPI.geoPositionUpdated.disconnect(onGeoPositionUpdated);
    desiteAPI.disableGeoLocation();
});

◆ cutObject

array< string > cutObject	(	string	parentId,
		string	objId,
		object	plane = `object()`,
		bool	closeCuts = `true`,
		bool	splitUnconnectedParts = `true`
	)

function

Cut object into subparts.

Parameters

parentId	ID of parent container. If empty, subparts will be added to object.
objId	ID of object
plane	Cutting plane - see code example below for format and default values.
closeCuts	Close mesh of cut parts.
splitUnconnectedParts	Split cut parts which are not connected (e.g. when cutting a U-shaped object horizontally). Note that this will only work on closed meshes (closeCuts = true).

Returns: ID list of subparts, empty list on error.

Example: Cut object ID="ABCxyz123" by xy-plane (through origin) and append parts to object:

const plane = {
    px : 0.0,
    py : 0.0,
    pz : 0.0,
    nx : 0.0,
    ny : 0.0,
    nz : 1.0,
}
const ids = desiteAPI.cutObject("", "ABCxyz123", plane);

Since: 1.5.0, 05 Aug 2015

◆ dbAssertTable

int dbAssertTable	(	string	tableName,
		array< string >	columnsList
	)

function

Check if database has a specific table with certain columns.

Parameters

tableName	Table name
columnsList	List of columns specified in the format [columnname columndatatype]

Example:

var tblName = "TestTable";
var colList = [ 'RecID string', 'colNmbr real' ];
desiteAPI.dbAssertTable( tblName, colList );

Returns: 1: Ok
-1: No database connection
-2: Failed to create table
-3: Execution blocked

Since: 2.0

◆ dbCheckIn

void dbCheckIn ( )

function

Database check-in.

Since: 1.0.17, 18 jul 2012, jh

Remarks: 1.5.0, 15 dec 2014, moved to class AutomationAPI

◆ dbCheckOut

void dbCheckOut ( array< string > propList )

function

Check out properties in local database. Only properties which are checked out can be edited. All other properties are locked in local database.

Parameters

propList List of properties in such format: propName##propType

Since: 1.0.17, 18 jul 2012, jh

◆ dbClearCache

int dbClearCache	(	string	propName,
		string	propType
	)

function

Returns: 1 - Ok
-1 - Error

Since: 1.3.6, 28 apr 2014, jh

◆ dbClearCacheAll

void dbClearCacheAll ( )

function

See also: To setup cached values see also itSetupDbCache()

Since: 1.3.6, 28 apr 2014, jh

◆ dbClose

bool dbClose ( )

function

Close the currently connected DB. Returns false if no DB was connected.

Since: 2.4.1, 2019-01-28, ah

◆ dbDeleteProperty

int dbDeleteProperty	(	string	objIdList,
		string	propName,
		string	propType
	)

function

Delete properties from database.

Parameters

objIdList The properties are removed and deleted from these objects.

Returns: 0 undefined
-3 execution blocked
-4 database is not open
-5 no objects found in domain projects

Since: 1.4.9, 12 Dec 2015

◆ dbEndQueryExec

bool dbEndQueryExec ( )

function

Free all resources bound to the last dbQueryExec.

Returns: true if there was an open dbConnection and has been closed successfully

Since: 2.1.6, 02 mar 2018, ar

◆ dbGetFilepath

string dbGetFilepath ( ) const

function

If the connected DB is file-based, returns the filename and path. Otherwise, an empty string is returned.

Since: 2.4.1, 2019-01-17, ah

◆ dbGetImmediateUpdate

bool dbGetImmediateUpdate ( )

function

See also: dbSetImmediateUpdate()

Since: 1.3.0, 14 nov 2013, jh

◆ dbIsLocalCopy

bool dbIsLocalCopy ( )

function

Check if current database is a local copy.

Since: 1.0.17, 18 jul 2012, jh

◆ dbOpen

int dbOpen ( const var connectionData = var() )

function

Open and connect a project database. Will do nothing if a database connection is already open.
Pass connection data as object.

Example:

{
    "FileName": "C:/db/test.db"
}

You can pass an empty object or no connection data at all. In that case, a DB will be opened with default parameters (in the current project's directory). Project must have been saved first.

Returns: 1 - Success
2 - DB already open and connected
-1 - Connection Error
-2 - Input Error (e.g. FileName missing and no project open)
-3 - Execution blocked

Since: 2.4.1, 2019-01-28, ah

◆ dbQueryExec

bool dbQueryExec ( string sqlQuery )

function

Create a database query by a SQL statement. To iterate over the query result use dbQueryNext() and get the values of the current record by dbQueryValue().

Parameters

sqlQuery Database query as SQL statement

Returns: true - success
false - query has failed

Since: 1.0.18, 14 aug 2012, jh

◆ dbQueryLastError

string dbQueryLastError ( )

function

Get the error message that the last executed SQL query returned (if any).

Since: 2.3.1, 12 dec 2018, ah

◆ dbQueryNext

bool dbQueryNext ( )

function

Go to next record of last query.

Returns: true - success
false - iterator is at end, no next query

See also: dbQueryExec()

Since: 1.0.18, 14 aug 2012, jh

◆ dbQueryRecordset

object dbQueryRecordset	(	string	sqlQuery,
		string	key,
		int	maxNumberOfRows = `0`
	)

function

Create a database query by SQL statement.

Parameters

sqlQuery	the SQL query string.
key	the field name used as key in record set returned. For more than one key value only the last one will be returned.
maxNumberOfRows	max number of rows in result set returned, left open or 0 for unlimited.

Example call: desiteAPI.dbQueryRecordset("SELECT matchKey, price FROM tblPrices", "matchKey", 0);

Returns: object holding a 'recordset' as a 2-dimensional array.

Example:

{
    "recordSet": {
        "96.62.003.0160": [424.7039],
        "96.62.003.0170": [424.70398],
        "96.62.004.0000": [0]
        },
    "fieldNames": [price],
    "key": "matchKey",
    "rowsFetched": 3,
    "rowsRequested": 0
}

Since: 2.1.6, 18 mar 2018, ar

◆ dbQueryValue

var dbQueryValue ( int column )

function

Since: 1.0.18, 14 aug 2012, jh

◆ dbSetImmediateUpdate

void dbSetImmediateUpdate ( bool )

function

See also: dbGetImmediateUpdate()

Since: 1.3.0, 14 nov 2013, jh

◆ deleteModel

int deleteModel ( string id )

function

Delete Model.

Contained elements are removed from all locations where they are used (links, viewpoints, ...) and will be deleted afterwards.

Parameters

id	ID of model

Returns: Error Code:
1 - Ok, model was deleted
-1 - Error, ID does not exist
-2 - Error, model is write protected
-3 - Error, model could not be removed

Since: 2.0.13, 25 Apr 2017

◆ deleteObjects

int deleteObjects ( string idList )

function

Delete and remove one or more objects or containers. Model root nodes will not be deleted!

Contained elements are also removed and deleted. Also these elements are removed from all other locations where they are used (links, viewpoints, ...)

Parameters

idList List of object/container IDs separated by ';'

Returns: Number of deleted objects and containers

Since: 1.3.0, 02 jan 2014, jh

◆ deleteProperty

int deleteProperty	(	string	objId,
		string	propName,
		string	propDatatype
	)

function

Delete property 'propName' with data type 'propDatatype' from the element identified by 'objId'.

Parameters

objId ID of element. Use 'GlobalProject' to remove and delete a global project property.

Returns: 0 - undefined
1 - ok, property does not exist for given object
2 - ok, property has been deleted
-1 - error, object 'objId' not found
-2 - error, no model found in which obj is contained
-3 - error, model is read only
-4 - error deleting a db or core property

Since: 1.5.0, 14 mar 2015, jh

◆ deletePropertyType

int deletePropertyType	(	string	propertyName,
		string	propertyDatatype,
		string	domainName = `"all"`
	)

function

Remove property type from domain. All affected properties will be deleted.
Note that for DB property types, this will only work if the type is defined for a single domain only. (To delete DB property types across all domains, use the database widget.)

Parameters

propertyName	Name of property type
propertyDatatype	Data type of property type
domainName	Name of domain (default: "all", combinations are allowed)

Returns: 1 - ok
0 - undefined
-1 - error, empty propertyName
-2 - error, invalid propertyType
-3 - error, invalid domainName
-4 - property type could not be deleted

Since: 1.5.0, 14 Dec 2015

◆ disableGeoLocation

void disableGeoLocation ( )

function

Disable tracking of your current geo location.

Since: 2.9.0, 11 Oct 2021; 3.1.0, 04 May 2022 : moved from CoreAPI

◆ enableGeoLocation

void enableGeoLocation ( int msecInterval = 60 )

function

Enable tracking of your current geo location, position will be updated by given interval in milliseconds.

Since: 2.9.0, 11 Oct 2021; 3.1.0, 04 May 2022 : moved from CoreAPI

◆ endProjectTransaction

int endProjectTransaction ( string domain = "geometry" )

function

Finish transaction on project of given domain.

See also: startProjectTransaction()

Returns: number of currently open project transactions

Since: 2.2.1, 02 aug 2018, sl

◆ endTransaction

bool endTransaction ( )

function

Finish database transaction.

Since: 1.0.18, 20 aug 2012, jh

◆ fileChunkReceived

void fileChunkReceived ( string data )

signal

Emitted by readFileInChunks() for transmitting data.

See also: readFileInChunks()

Since: 3.2.5, 22 Aug 2023

◆ filterByProperty

array< string > filterByProperty	(	array< string >	inputList,
		string	propertyName,
		string	propertyDatatype,
		string	filterPattern,
		bool	checkInherited = `true`,
		string	domains = `"geometry"`
	)

function

Apply a property filter on a list of elements.

Parameters

inputList	Source list of element IDs that the filter will be applied to
propertyName	Property name
propertyDatatype	Property data type ('xs:string', 'xs:double', 'xs:long', ...)
filterPattern	Filter string. This can either be in standard VDC Manager filter format (supports asterisks, space means OR, not case sensitive) or a Regular Expression in JavaScript notation.
checkInherited	[optional] Check inherited properties, too (true by default)
domains	[optional] Domain(s) to be checked ('geometry' by default)

Returns: List of element IDs that passed the filter

Example:
Filter and show geometric elements with more than 100 vertices and which names begin with "Basic"

var filteredList = desiteAPI.getAllElements('geometry');
filteredList = desiteAPI.filterByProperty(filteredList, 'cpCountVertices', 'xs:long', '>100', false, 'geometry');
filteredList = desiteAPI.filterByProperty(filteredList, 'cpName', 'xs:string', 'Basic*', false, 'geometry');
desiteAPI.showElementsOnly(filteredList);

Since: 2.9.3, 17 Mar 2022

◆ filterByStatus

array< string > filterByStatus	(	array< string >	inputList,
		string	status,
		bool	value = `true`,
		string	domains = `"geometry"`
	)

function

Apply a status filter on a list of elements.

Parameters

inputList	Source list of element IDs that the filter will be applied to
status	Status as string, one of ['visible', 'selected']
value	[optional] Value of status, either true (default) or false
domains	[optional] Domain(s) to be checked ('geometry' by default)

Returns: List of element IDs that passed the filter

Example:
Filter for selected geometric elements

var filteredList = desiteAPI.getAllElements('geometry');
filteredList = desiteAPI.filterByStatus(filteredList, 'selected', true, 'geometry');
console.log(filteredList);

Since: 2.9.3, 17 Mar 2022; 3.5.0, 01 Oct 2024 : status 'locked' abolished

◆ findContainerByName

string findContainerByName	(	string	parentId,
		string	name,
		string	lookupDomain = `"all"`
	)

function

Get container with name 'name' and parent node 'parentId'. If the container does not exist, an empty string is returned.
Note that a name is not necessarily unique; this method will only return the first match.

Parameters

parentId	Parent node ID
name	Name of the container
lookupDomain	Lookup container 'name' in this domain, default = 'all'

Returns: container ID

Since: 1.5.0, 10 Dec 2014

◆ findDocumentsByDate

array< string > findDocumentsByDate	(	date	start,
		date	end,
		array< string >	idList = `array< string >()`,
		bool	useRef = `false`
	)

function

Get documents where the creation date is between a given range or where the reference date is between a given range.

Parameters

start	Start of date range
end	End of date range
idList	(optional) List of IDs of documents. If empty, all documents will be considered.
useRef	(optional) Flag determining if documents are searched by their create or reference date

Since: 2.0.0, 20 jun 2016

◆ findDocumentsByLocationGk

array< object > findDocumentsByLocationGk	(	double	rw,
		double	hw,
		double	distance,
		array< string >	idList = `array< string >()`
	)

function

Get documents which are located around a given point in Gauss-Krueger coordinates by a given distance.

Parameters

rw	'Rechtswert' (x-coordinate) of search point
hw	'Hochwert' (y-coordinate) of search point
distance	Search range
idList	(optional) List of IDs of documents. If empty, all documents will be considered.

Since: 2.0.0, 20 Jun 2016

◆ findDocumentsByLocationGps

array< object > findDocumentsByLocationGps	(	double	lat,
		double	lon,
		double	distance,
		array< string >	idList = `array< string >()`
	)

function

Get documents which are located around a given point in GPS coordinates by a given distance.

Parameters

lat	Latitude of search point
lon	Longitude of search point
distance	Search range
idList	(optional) List of IDs of documents. If empty, all documents will be considered.

Since: 2.0.0, 20 Jun 2016

◆ findDocumentsByLocationRangeGps

array< object > findDocumentsByLocationRangeGps	(	array< string >	gpsCoordinates,
		double	distance,
		array< string >	idList = `array< string >()`
	)

function

Get documents which are located around a given point list in GPS coordinates by a given distance.

Parameters

gpsCoordinates	List of GPS coordinates (lat/lon) as string, delimited by ';', e.g. ['51.4556;7.0116',...]
distance	Search range
idList	(optional) List of IDs of documents

Since: 2.0.0, 20 Jun 2016; 3.0.0, 19 Apr 2022 : Changed delimiter from '#' to ';' as used by properties

◆ geoPositionUpdated

void geoPositionUpdated ( object pos )

signal

Emitted when current geo position got updated.
Location tracking has to be active (call desiteAPI.enableGeoLocation).

Example:

desiteAPI.geoPositionUpdated.connect(function(pos)
{
    console.log('Latitude: ' + pos['Lat'] + ', Longitude: ' + pos['Lon']);
});

Since: 2.9.0, 11 Oct 2021; 3.1.0, 04 May 2022 : moved from CoreAPI

◆ getActiveColorScheme

string getActiveColorScheme ( )

function

Get ID of active color scheme. Empty string for no color scheme.

Returns: ID of active color scheme.

Since: 3.5.0, 10 Apr 2024

◆ getAllElements

array< string > getAllElements ( string domainFilter = "geometry" )

function

Get IDs of all elements as an array.

Parameters

domainFilter Get all IDs of given domain(s)

Returns: List of element IDs

Since: 2.2.4, 06 Nov 2018; 3.1.3, 02 Dec 2022 : moved from ProjectAPI to AutomationAPI

◆ getAsJSON

object getAsJSON ( string objId )

function

Get geometric object data.

Example:

var objidList = desiteAPI.getSelected();
var idList = objidList.split(';');
for ( n in idList ) {
    var id = idList[n];
    if( id.length < 1 ) continue;
    var objJSON = desiteAPI.getAsJSON(id);
    console.log( JSON.stringify(objJSON, undefined, 2) );
}

A 3D-object that contains vertices, triangles and faces (uv is available only if texture is attached on the surface).
Note: the triangle list - unlike the face list - is not grouped; each consecutive triple of vertex indices forms a triangle
Example Result:

{
  "ElementType": "surface",
  "ID": "ccf5ac9b-6eeb-4134-a9d0-558bf92b9a8e",
  "Name": "Basisdecke [2409746]",
  "faceList": [
    [
      0,
      1
    ]
  ],
  "triangleList": [
    0,
    1,
    3,
    3,
    2,
    0
  ],
  "uv": [
    105.5401840209961,
    152.18524169921875,
    105.5401840209961,
    134.1296844482422,
    126.3735122680664,
    134.1296844482422,
    126.3735122680664,
    134.1296844482422,
    126.3735122680664,
    152.18524169921875,
    105.5401840209961,
    152.18524169921875
  ],
  "vertexList": [
    18.99723345336914,
    27.393344219970704,
    2.600000019836426,
    18.99723345336914,
    24.143344921875002,
    2.600000019836426,
    22.74723246459961,
    27.393344219970704,
    2.600000019836426,
    22.74723246459961,
    24.143344921875002,
    2.600000019836426
  ]
}

Since: 2.1.0, 2017-05-30, jh; 2.7.3, 2021-01-11, ek: faceList added

◆ getBBoxMaxX

double getBBoxMaxX ( )

function

Get maximal x-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBBoxMaxY

double getBBoxMaxY ( )

function

Get maximal y-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBBoxMaxZ

double getBBoxMaxZ ( )

function

Get maximal z-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBBoxMinX

double getBBoxMinX ( )

function

Get minimal x-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBBoxMinY

double getBBoxMinY ( )

function

Get minimal y-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBBoxMinZ

double getBBoxMinZ ( )

function

Get minimal z-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBoundingBoxCommon

object getBoundingBoxCommon ( var objectIds )

function

Get common bounding box of all given objects. If an object ID represents a composite (geometric container), all parts of it will be taken into account.

Parameters

objectIds IDs of objects to be affected (array or string, using ';' as separator)

Returns: JSON object with min and max coordinates of bounding box, e.g.
{
minX: 0.0,
minY: 0.0,
minZ: 0.0,
maxX: 2.0,
maxY: 2.0,
maxZ: 2.0
}

Since: 1.4.10, 10 Jun 2015; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ getCalendarByName

string getCalendarByName ( string name )

function

Get calendars with given name.

Parameters

name	Name of calendar

Returns: ID(s) of calendar(s), empty string if name was not found

Since: 2.8.5, 14 Oct 2021; 3.4.2, 09 Apr 2024 : If the name is not unique (multiple calendars found), the return string will no longer be the first found ID, but a concatenation (separated by ;)

◆ getCalendarByTask

string getCalendarByTask	(	string	taskID,
		bool	checkInh = `true`
	)

function

Get calendar assigned to a task. Note: If no calendar is explicitly assigned to a task, the ID of the default calendar will be returned.

Parameters

taskID	ID of task
checkInh	Also check inherited calendars

Returns: ID of calendar

Since: 2.8.5, 14 Oct 2021

◆ getCalendarExceptions

array< object > getCalendarExceptions ( string calendarID )

function

Get list of calendar exceptions (user defined days or holidays).

Parameters

calendarID ID of the calendar

Returns: List with exceptions

Example return:

[
    {
        "Date" : "2022-12-24",
        "WorkingTime" : [["08:00","12:00"]],
        "Comment" : "Christmas Evening"
    },
    {
        "Date" : "2023-01-01",
        "WorkingTime" : [],
        "Comment" : "New Year"
    }
]

Since: 2.9.2, 03 Mar 2022

◆ getCalendarList

array< string > getCalendarList ( )

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Get available calendars.

Returns: List of calendar IDs

Since: 2.8.5, 14 Oct 2021; 3.4.2, 10 May 2024 : deprecated

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

◆ getCalendarOptions

object getCalendarOptions ( string calendarID )

function

Get default options of calendar.

Parameters

calendarID ID of the calendar

Returns: Options

Example return:

{
    "DefaultStartTime" : "08:00",
    "DefaultFinishTime" : "17:00",
    "HoursPerDay" : 8,
    "HoursPerWeek" : 40,
    "DaysPerMonth" : 20
}

Since: 2.8.6, 28 Feb 2022

◆ getCalendarWorkingTime

object getCalendarWorkingTime ( string calendarID )

function

Get weekly working time.

Parameters

calendarID ID of the calendar

Returns: Weekly working time

Example return:

{
    "Monday" : [["08:00","12:00"],["13:00","17:00"]],
    "Tuesday" : [["08:00","12:00"],["13:00","17:00"]],
    "Wednesday" : [["08:00","12:00"],["13:00","17:00"]],
    "Thursday" : [["08:00","12:00"],["13:00","17:00"]],
    "Friday" : [["08:00","14:00"]],
    "Saturday" : [],
    "Sunday" : []
}

Since: 2.9.2, 03 Mar 2022

◆ getCheckActive

var getCheckActive ( string checkRunID ) const

function

Returns whether check run is active or not.

Parameters

checkRunID ID of checkRun

Returns: Active state of check run or undefined in case it doesn't exist.

See also: setCheckActive()

Since: 3.5.0, 22 Nov 2024

◆ getCheckFilterList

array< object > getCheckFilterList	(	string	checkRunID,
		bool	rightSet = `false`
	)		const

function

Get object filter for check- or clash run.

Parameters

checkRunID	ID of checkRun
rightSet	In case of clash runs, set filter for left (= false) or right (= true) object set

Returns: List of filter items, empty list if check run with given ID does not exist

Since: 2.9.0, 01 Oct 2021

◆ getCheckItems

array< string > getCheckItems	(	string	checkRunID,
		bool	rightSet = `false`
	)		const

function

Get elements (explicitly set) to be processed by check- or clash run. Note: The IDs of the element/containers to be checked are returned, not the IDs of the check items itself

Parameters

checkRunID	ID of checkRun
rightSet	In case of clash runs, set filter for left (= false) or right (= true) object set

Returns: List of element ids, empty list if check run with given ID does not exist

Since: 2.9.0, 14 Jan 2022

◆ getCheckOptions

object getCheckOptions ( string checkRunID ) const

function

Get options of a Model Check Run.

Parameters

checkRunID ID of Check Run

Returns: Options as object, empty object if check run with given ID does not exist

See also: setCheckOptions()

Since: 2.9.0, 01 Oct 2021; 3.5.0, 24 Sept 2024 : This function is no longer used for Clash Detection settings. Use getClashDetectionSettings() instead.

◆ getCheckRules

object getCheckRules	(	string	checkRunID,
		string	ruleTypeFilter = `string()`
	)

function

Get check rules of check run.

Parameters

checkRunID	ID of (model) check run
ruleTypeFilter	Type of check rule. If empty, all check rules will be returned. "ScriptRule" "AttributeRule" "UniquePattern"

Returns: {
"ScriptRules" : [
{
"Comment": "",
"ID": "cb41d9fa-ad4f-4eb5-8ba7-a3a983511f47",
"IsActive": true,
"Name": "newRule",
"ResumeOnError": true,
"Code": "// write some code here"
}
],
"AttributeRules" : [
{
"Comment": "If-Check for rooms",
"ID": "06527951-b45c-4f78-9a50-63a405ca132e",
"ParentID": "",
"Pattern": "IfcSpace",
"PropertyTypeKey": "ifcType##xs:string",
"SubType": "conditional"
},
{
"Comment": "Comment3",
"ID": "1389dabd-b76e-4506-8c4a-1cc8f942b391",
"ParentID": "06527951-b45c-4f78-9a50-63a405ca132e",
"Pattern": "A*",
"PropertyTypeKey": "cpName##xs:string",
"Type": "simple"
}
],
"UniquePatterns" : [
{
"CheckInherited": true, // currently unused!
"Comment": "Check uniqueness of element IDs",
"Pattern": "[[cpID##xs:ID]]"
}
],
}

Since: 2.9.3, 24 Mar 2022

◆ getClashRunSettings

var getClashRunSettings ( string clashRunID ) const

function

Get settings of a clash detection run.

Parameters

clashRunID ID of the clash run

Returns: Current settings or undefined in case of an invalid ID

{
    clashes: {
    checkEnabled: true, // Enables or disables the detection of clashes between objects.
    calculateCuttingLines: true, // Calculates intersection lines for intersecting triangles. These lines, along with their bounding boxes, are displayed when a clash result is shown.
    allowTouches: true, // Objects that are only slightly touching (1 millimeter) won’t be detected as clashes.
    checkInclusions: false, // Detect if objects are fully enclosed within others.
    considerOnlyInclusions: "None", // ( "None", "LeftIncludesRight", "RightIncludesLeft" "Bidirectional" ) Ignore clashes and only consider objects that are inside other objects.
},
    contacts: {
    checkEnabled: false, // Enables or disables the detection of contacts between objects.
    createAsObjects: false, // Generates contact areas as 3D objects.
    maxFaceDistance: 0.0, // Specifies the maximum allowed distance between contacting faces.
    maxAngleDeviation: 0.0, // Specifies the maximum allowed angular deviation between the normals of contacting faces.
    checkOppositeFacesOnly: false, // If enabled, only opposite faces of objects are considered for contact detection.
    checkTop: false, // Enables or disables the detection of contact at the top of the object.
    checkBottom: false, // Enables or disables the detection of contact at the bottom of the object.
    checkLateral: false // Enables or disables the detection of lateral contact on the object.
},
    equality: {
    compareBoundingBox: false, // Enables bounding box check for object equality.
    boundingBoxTolerance: 0.0, // Specifies the position tolerance for bounding box comparison.
    compareVolume: false, // Enables volume check for object equality.
    volumeTolerance: 0.0, // Specifies the tolerance for volume comparison.
    compareSurfaceArea: false, // Enables surface area check for object equality.
    surfaceAreaTolerance: 0.0 // Specifies the tolerance for surface area comparison.
},
    distances: {
    check: "None", // ( "None", "Minimum", "Maximum" ) Ensures that objects maintain a minimum required distance from each other or do not exceed a specified maximum distance.
    minimum: 0.0, // Sets the minimum required distance that objects must maintain from one another.
    maximum: 0.0, // Sets the maximum allowed distance that objects can have between each other.
    checkHorizontalOnly: false // Considers only horizontal distances between objects.
},
    leftSet: {
    reportItemsWithNoResults: false, // Generates a result item if an object in the specified sets does not meet any of the defined checks.
    keepComposites: true, // Generate results based on the composite object, rather than on each individual part.
    clearanceSpaces: {
    checkEnabled: false, // Checks clearance spaces of objects in intersection- and inclusion checks.
    creationMode: "OBBxy", // ( "OBBxy", "OBB" ) Defines whether the clearance space is calculated using the oriented bounding box (OBB) or a restricted oriented bounding box (OBBxy), which limits rotation to the vertical Z-axis.
    automaticSize: false, // Automatically determines the size of the clearance space based on the length of the oriented bounding box.
    extrusion: 0.0 // Specifies the dimension of the working space perpendicular to the object.
}
},
    rightSet: {
    reportItemsWithNoResults: false, // Generates a result item if an object in the specified sets does not meet any of the defined checks.
    keepComposites: true, // Generate results based on the composite object, rather than on each individual part.
    clearanceSpaces: {
    checkEnabled: false, // Checks clearance spaces of objects in intersection- and inclusion checks.
    creationMode: "OBBxy", // ( "OBBxy", "OBB" ) Defines whether the clearance space is calculated using the oriented bounding box (OBB) or a restricted oriented bounding box (OBBxy), which limits rotation to the vertical Z-axis.
    automaticSize: false, // Automatically determines the size of the clearance space based on the length of the oriented bounding box.
    extrusion: 0.0 // Specifies the dimension of the working space perpendicular to the object.
}
}
}

See also: setClashDetectionSettings()

Example:

const clashRunID = "a6daca3e-9308-41f9-b1c9-89a33ddd9e8b";
const settings = desiteAPI.getClashRunSettings(clashRunID);
console.log(JSON.stringify(settings, null, 4));

Since: 3.5.0, 24 Sept 2024

◆ getColorItemData

var getColorItemData ( string colorItemID )

function

Retrieve attributes for the passed in color item like the name or color.

Parameters

colorItemID ID of the color item

Returns: {
"name": "Blue",
"color": { r: 0, g: 0, b: 1, a: 0.3 },
"outline": true
}

Since: 3.5.0, 10 Apr 2024

◆ getColorItemsFromColorScheme

var getColorItemsFromColorScheme ( string colorSchemeID )

function

Get list of color items from given color scheme or undefined in case color scheme doesn't exist.

Returns: List of color item IDs

Since: 3.5.0, 26 Aug 2024

◆ getColorSchemeData

var getColorSchemeData ( string colorSchemeID )

function

Retrieve attributes for the passed in color scheme like the name.

Parameters

colorSchemeID ID of the color scheme

Returns: {
"name": "My Color Scheme",
"focused": false,
"systemOwned": false,
}

Since: 3.5.0, 10 Apr 2024

◆ getColorSchemeList

array< string > getColorSchemeList ( )

function

Get list of all available color schemes.

Returns: List of color scheme IDs

Since: 3.5.0, 10 Apr 2024

◆ getDefaultCalendar

string getDefaultCalendar ( )

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Get default calendar.

Returns: ID of calendar

Since: 2.9.3, 08 Mar 2022; 3.4.2, 10 May 2024 : deprecated

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

◆ getDirectoryEntryList

array< object > getDirectoryEntryList	(	string	dirPath,
		bool	filesOnly = `false`,
		string	orderBy = `"Name"`
	)

function

Return a list of all files and (optionally) subdirectories in the given directory.
The list will NOT include system and hidden files.
A Windows environment variable can be used, but only once in the string (e.g. 'userprofile%/pictures')
Objects in the returned list will contain the following keys:

Name
AbsoluteFilePath
AbsolutePath
SizeInBytes
CreationDateTime
LastModifiedDateTime
IsReadable
IsWritable
IsDirectory

Parameters

dirPath	Full path to the directory to scan
filesOnly	(default false) if this is set to true, subdirectories will not be included in the list
orderBy	Sort the result list either by "Name" (alphabetically, default), "Size" (largest first), or "Time" (most recently modified first)

Returns: Object list with each object representing a file or a subdirectory found in the given directory.
If the source directory was not found or an error occurred, the list will be empty.

Since: 2.0.16, 17 oct 2017, ah

◆ getElementsFromColorItem

var getElementsFromColorItem ( string colorItemID )

function

Get list of elements from given color item or undefined in case the color item doesn't exist.

Returns: List of element IDs

Since: 3.5.0, 26 Aug 2024

◆ getListOfObjTooltips

array< string > getListOfObjTooltips ( )

function

Get list of tooltip templates.

Since: 1.3.2, 28 mar 2014, jh

◆ getListOfTempValues

array< string > getListOfTempValues ( )

function

Get list of temporary values.

Since: 2.4.1, 11 feb 2019, jh

◆ getMaterialData

var getMaterialData ( string materialID )

function

Retrieve attributes for the passed in material like name or color.

Parameters

materialID ID of the material

Returns: {
"ambient": { a: 1, b: 1, g: 1, r: 1 },
"diffuse": { a: 1, b: 1, g: 1, r: 1 },
"name": "newMaterial",
"shininess": 0.5,
"specular": { a: 1, b: 1, g: 1, r: 1 },
"transparency": 0
}

Since: 3.4.1, 08 Feb 2024

◆ getMaterialIDByName

string getMaterialIDByName ( string matName )

function

Get ID of material with given name.

Parameters

matName Name of material

Returns: ID of material. If material does not exist an empty string is returned.

Since: 1.0.20, 14 jan 2013, jh

◆ getMaterialList

array< string > getMaterialList ( )

function

Get list of all available materials.

Returns: List of material IDs

Since: 1.0.20, 14 Jan 2013

◆ getModelByElement

string getModelByElement	(	string	id,
		string	domainFilter = `"all"`
	)

function

Lookup the parent model of the element with the given ID. If the model could not be found, this method returns an empty string.

Parameters

id	Element ID to find the model of
domainFilter	[optional] Domain(s) to look in; by default "all". The lookup may be faster if you narrow the search to specific domains.

Since: 1.9.0, 13.05.2016, jh

◆ getModelImportSettings

var getModelImportSettings ( string modelID )

function

Get settings the model was imported with.

Parameters

modelID ID of model

Since: 3.3.0, 21 Aug 2023

◆ getModelListByDomain

array< string > getModelListByDomain ( string domainFilter = "all" )

function

Return a ID-list of all models in a given domain.
NOTE: The model ID is not identical to the ID of the model root nodes in the element hierarchies.

Parameters

domainFilter Given domain(s) (default = 'all'). Different domain names have to be separated by ';'.

See also: getRootNodeListByDomain()

Since: 1.5.0, 28 oct 2015, jh

◆ getModelListByName

array< string > getModelListByName	(	string	name,
		string	domain = `"geometry"`
	)

function

Get a list of IDs of all models with name 'name'.
NOTE: The model ID is not identical to the ID of the model root nodes in the element hierarchies.

name : Name of the model domain : Domain name combination. Default is 'geometry'

See also: DOMAINS

Returns: model IDs as list

See also: string getRootNodeByModel(string modelID)

Since: 1.3.0, 02 jan 2014, jh

◆ getModelMetaData

object getModelMetaData ( string modelID )

function

Get meta data of a given model as JSON object.

Keys of JSON object:

ExportFileName
ExportFileNameUser
ExportCreated
ExportCreatedBy
SourceModelID
SourceApp
SourceFormat
SourceFileName
ProjectFileName
ProjectModelRecID
ProjectDbLink
ProjectUrl
Imported
ImportedBy
ExportFormatName
ExportFormatVersion

Since: 1.5.0, 28 oct 2015, jh

◆ getOOBBCommon

object getOOBBCommon ( var objectIds )

function

Calculate the common OOBB of all given objects. The OOBB is not explicitly set to affected objects and cannot be re-used (see properties cpOOBB... and so on). If an object ID represents a composite or geometric container, all parts of it will be taken into account.

Parameters

objectIds IDs of objects to be affected (array or string, using ';' as separator)

Returns: JSON object with 4 arrays specifying the origin and the 3 axis which define the OOBB, e.g.
{
origin: [0.0,0.0,0.0],
axis1: [1.0,0.0,0.0],
axis2: [0.0,1.0,0.0],
axis3: [0.0,0.0,1.0]
}

Since: 2.1.0, 09 May 2017; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ getOOBBxyCommon

object getOOBBxyCommon ( var objectIds )

function

Calculate the common OOBBxy of all given objects. The OOBBxy is not explicitly set to affected objects and cannot be re-used (see properties cpOOBBxy... and so on). If an object ID represents a composite or geometric container, all parts of it will be taken into account.

Parameters

objectIds IDs of objects to be affected (array or string, using ';' as separator)

Returns: JSON object with 4 arrays specifying the origin and the 2 axis and a height which define the OOBBxy, e.g.
{
origin: [0.0,0.0],
axis1: [1.0,0.0],
axis2: [0.0,1.0],
height: 1.2
}

Since: 2.1.0, 09 May 2017; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ getProjectionAsSvg

string getProjectionAsSvg	(	var	idList,
		object	options = `object()`
	)

function

Get projection of given geometric objects as SVG.

Parameters

idList	IDs of geometric objects. Can be passed as an array or a string (semicolon-separated).
options	Options, see example below. If an empty object is passed, the size and viewBox are adjusted to the drawn objects.

Returns: SVG code

Example Options:

{
    "width": 600,
    "height": 200,
    "viewBox": "10 10 800 400",
    "resolution": 72
}

Since: 2.0.9, 03 Feb 2017

◆ getPropertyListAsJSON

object getPropertyListAsJSON ( object options )

function

Get list of properties.

This is the same format as the export/import of properties used by the GUI.

Parameters

opt	Options to configure the export.

Example:

var opt = {
    "ExportVisibleObjects":         true,                                           // default: false (means all, visible or not)
    "ActivePropertiesBookmark":     "EXP_STATUS",                                   // if no bookmark is given, all properties are returned,
                                                                                    // if "PropertyTypeList" is used, this setting will be ignored altogether
    "ExportInheritedProperties":    true,                                           // default: true
    "EvaluateProperties":           true,                                           // default: true
    "PropertyTypeList":             [ "cpCount##xs:long", "WebTest##xs:string" ],   // export contained property types. this will override "ActivePropertiesBookmark".
    "Domains":                      [ "geometry" ],                                 // passing a string (semicolon-separated) instead of a "true" list will also work (default: all)
    "ReportNull":                   true                                            // Get also property values as 'null' if property does not exist for a specific object (default: false)
};
var g = desiteAPI.getPropertyListAsJSON(opt);
console.log( JSON.stringify(g) );

Since: 2.2.1, 20 jun 2018, jh

Remarks: , 2.5.3, jh, Parameter 'ReportNull' added

◆ getPropertyScriptBgColor

string getPropertyScriptBgColor	(	string	domain,
		string	pname,
		string	datatype
	)		const

function

Get code (background) of property script.

Since: 2.5.0, 06 mar 2019, jh

◆ getPropertyScriptCode

string getPropertyScriptCode	(	string	domain,
		string	pname,
		string	datatype
	)		const

function

Get code (value) of property script.

Since: 2.5.0, 06 mar 2019, jh

◆ getPropertyScriptFgColor

string getPropertyScriptFgColor	(	string	domain,
		string	pname,
		string	datatype
	)		const

function

Get code (foreground) of property script.

Since: 2.5.0, 06 mar 2019, jh

◆ getPropertyScriptList

object getPropertyScriptList ( ) const

function

Get list of property scripts as JSON object.

Example:

{
    "activities": [
        {
            "DataType": "xs:double",
            "DisplayName": "PROP_B",
            "Name": "PROP_B",
            "Unit": ""
        }
    ],
    "boq": [],
    "building": [],
    "cd": [],
    "documents": [],
    "geometry": [
        {
            "DataType": "xs:string",
            "DisplayName": "PROP_A",
            "Name": "PROP_A",
            "Unit": ""
        }
    ],
    "pc": [],
    "qa": [],
    "res": [],
    "type": []
}

Since: 2.5.0, 06 mar 2019, jh

◆ getPropertyScriptOptions

object getPropertyScriptOptions	(	string	domain,
		string	pname,
		string	datatype
	)

function

options {
    "IsCached": true,
    "IsInheritable": true,
    "Unit": "m2",
    "DisplayName": "abc"
}

Since: 2.5.0, 10 Mar 2019

◆ getPropertyTypeBookmark

object getPropertyTypeBookmark ( string name )

function

Get the data of a property type bookmark.

{
    "ID": "a0373145-30f9-4f81-84cb-65d1186dc7a0",
    "Name": "AREA",
    "Type": 2, // The 'Type' of the bookmark is 1 for User-defined and 2 for Global.
    "PropertyTypes": {
        "activities": [],
        "boq": [],
        "building": [],
        "cd": [],
        "documents": [],
        "geometry": [{
            "name": "cpLateralArea",
            "type": "xs:double"
        },
        {
            "name": "cpTopArea",
            "type": "xs:double"
        }],
        "pc": [],
        "qa": [],
        "res": [],
        "type": []
    }
}

Parameters

name	Name of the bookmark.

Deprecated:: The ID parameter is deprecated and will be removed in future updates. Always refer to bookmarks by name in new scripts.

Since: 3.5.0, 12 mar 2025

◆ getPropertyTypeBookmarkByID

object getPropertyTypeBookmarkByID ( string id )

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Get the data of a property type bookmark by ID.

{
    "ID": "a0373145-30f9-4f81-84cb-65d1186dc7a0",
    "Name": "AREA",
    "Type": 2, // The 'Type' of the bookmark is 1 for User-defined and 2 for Global.
    "PropertyTypes": {
        "activities": [],
        "boq": [],
        "building": [],
        "cd": [],
        "documents": [],
        "geometry": [{
            "name": "cpLateralArea",
            "type": "xs:double"
        },
        {
            "name": "cpTopArea",
            "type": "xs:double"
        }],
        "pc": [],
        "qa": [],
        "res": [],
        "type": []
    }
}

Parameters

id	ID of the bookmark to look up. If the ID isn't found, an empty object is returned.

Since: 2.2.4, 27 oct 2018

Deprecated:: Use getPropertyTypeBookmark() instead.

◆ getPropertyTypeBookmarkList

array<var> getPropertyTypeBookmarkList ( )

function

Return list of property types bookmarks.

Example:

[
    {
        "ID": "57d490e2-8900-42cd-b04d-4cbf84f1da8f",
        "Name": "EXPORT_BBOX",
        "Type": 2
    },
    {
        "ID": "8ddf3747-a6d7-428e-afa9-5cc3ecb20ad5",
        "Name": "BKM2",
        "Type": 2
    },
    {
        "ID": "a0373145-30f9-4f81-84cb-65d1186dc7a0",
        "Name": "AREA",
        "Type": 2
    }
]

Deprecated:: The ID parameter is deprecated and will be removed in future updates. Always refer to bookmarks by name in new scripts.

Since: 2.2.4, 27 oct 2018, jh

◆ getPropertyValues

array<var> getPropertyValues	(	string	propName,
		string	propDatatype,
		int	maxValues = `0`,
		string	domainName = `"all"`,
		bool	getNullValues = `false`
	)

function

Get all available property values for a given property type and domain.

Parameters

propName	Name of property type
propDatatype	Data type of property type
maxValue	Max. number of values which should be returned. If 'maxValue' = 0 all available values will be returned.
domainName	Name of domain (default: "all", combinations are allowed)

Returns: Array with all property values
Empty array if an error occurred or no property values are found in given domain(s)

See also: getPropertyValuesByObjectList()

Since: 1.5.0, 15 dez 2015, sl

◆ getPropertyValuesByObjectList

array<var> getPropertyValuesByObjectList	(	string	propertyName,
		string	propertyDatatype,
		bool	checkInherited,
		var	objectIdList,
		int	maxValues = `0`,
		string	domains = `"all"`,
		bool	getNullValues = `false`
	)

function

Get all available different property values for a given property type, list of objects and domain.

Parameters

propertyName	Name of property type
propertyDatatype	Data type of property type
checkInherited	true = Consider inherited properties, false = Check direct properties only
objectIdList	IDs of objects to check property values of
maxValues	[optional] Max. number of values which should be returned (pass <= 0 for all)
domains	[optional] Domain(s) to check (default: "all")
getNullValues	[optional] Set true if result list shall contain NULL values for objects not having this property.

Returns: Array with all property values
Empty array if an error occurred or no property values are found in given domain(s)

See also: getPropertyValues()

Since: 1.5.0, 15 Dez 2015; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ getRootContainerList

array< string > getRootContainerList ( string modelName )

function

Get a list of IDs of all root containers of all models with name 'modelName'. Works only in domain geometry, because not the model roots but the 'red' root containers (where transformations can be applied) are returned.

Parameters

modelName : Name of the model(s)

Returns: Container IDs as list

Since: 1.0.18, 19 Aug 2012

◆ getRootNodeByModel

string getRootNodeByModel ( string modelID )

function

Get ID of root node of a given model.

Each model has a container as root node in which the whole object hierarchy of a model is stored. This root node is visible in the tree view. The model itself is not visible in the GUI but can be accessed by methods in the API.

Returns: ID of root node, else empty string if 'modelID' is not an ID of any model.

See also: getRootNodeListByDomain()

Since: 1.5.0, 28 oct 2015, jh

◆ getRootNodeListByDomain

array< string > getRootNodeListByDomain ( string domainFilter = "all" )

function

Get list of IDs of root nodes of a given domain filter.

Each model has a container as a root node in which the whole object hierarchy of a model is stored.

Parameters

domainFilter Given domain(s) (default = 'all'). Different domain names have to be separated by ';'.

Since: 1.5.0, 28 oct 2015, jh

See also: getRootNodeByModel()

◆ getRootNodeListSelectionSets

array< string > getRootNodeListSelectionSets ( string domainFilter = "all" )

function

Get root nodes of selection sets. These root nodes are the top level selection sets in a domain project.

Remarks: Currently (2.2.2) domain 'geometry' is supported only.

Since: 2.2.2, 28 aug 2018, jh

◆ getTaskRestrictionsByName

string getTaskRestrictionsByName ( string name )

function

Get first task restriction with given name.

Parameters

name	Name of task restriction

Returns: ID of task restriction, empty string else

Since: 2.8.5, 14 Oct 2021

◆ getTaskRestrictionsList

array< string > getTaskRestrictionsList ( )

function

Get available task restrictions.

Returns: List of task restriction IDs

Since: 2.8.5, 14 Oct 2021

◆ getTempValue

var getTempValue ( string name )

function

Retrieve a temporarily stored property.

Since: 2.4.1, 02 feb 2019, ar

◆ getVisualisationList

object getVisualisationList ( )

function

Get list of visualization configurations as JSON object.

Example:

{
"list":[
        {
            "id":"{9ba5d816-1db8-43c1-8985-100d8c95610b}-6f",
            "name":"MW"
        },
        {
            "id":"{9ba5d816-1db8-43c1-8985-100d8c95610b}-70",
            "name":"StB"
        }
    ]
}

Since: 1.9.0, 16 jul 2016, jh

◆ hasColorItem

bool hasColorItem ( string colorItemID )

function

Returns whether the color item exists or not.

Parameters

colorItemID ID of the color item

Since: 3.5.0, 27 Aug 2024

◆ hasColorScheme

bool hasColorScheme ( string colorSchemeID )

function

Returns whether the color scheme exists or not.

Parameters

colorSchemeID ID of the color scheme

Since: 3.5.0, 27 Aug 2024

◆ hasContact

int hasContact	(	string	objId1,
		string	objId2,
		object	options = `object()`
	)

function

Check if two objects have contact.

Parameters

objId1	: ID of object 1
objId2	: ID of object 2
options	: Options encoded as JSON. If not specified, the default values of the code snipped (see below) will be chosen.

Returns: 1 if objects have contact using given options
0 - no contact -1 - error, object 'objId1' not found or of wrong type
-2 - error, object 'objId2' not found or of wrong type

var opt = {
    locflag: 7,     // 1 = contact at top, 2 = contact at bottom, 4 = contact at sides (and combinations)
    checkall: true, // if true, all given location combination checks must be true
    tol: 0.001,     // maximum distance tolerance [m]
    angle: 5.0,     // maximum angle deviation between normal vectors of opposite faces [�]
    oppdir: true,   // flag that indicates that normal vectors of contacting faces must point in opposite directions
}
desiteAPI.hasContact( id1, id2, opt );

Since: 1.5.0, 10 Dec 2014

◆ hasElement

bool hasElement ( string id )

function

Check if an object or container with the given ID exists.

Since: 1.3.0, 21 Jan 2014

◆ hasMaterial

bool hasMaterial ( string materialID )

function

Returns whether the material exists or not.

Parameters

materialID ID of the material

Since: 3.5.0, 27 Aug 2024

◆ hasModel

bool hasModel ( string modelID )

function

Returns whether the model exists or not.

Parameters

modelID ID of model

Since: 3.5.0, 27 Aug 2024

◆ isContainer

bool isContainer ( string id )

function

Checks if the object with the given ID is a container.

Since: 16 Mar 2015

Parameters

id	: Object ID

Returns: true or false

◆ isIncludedIn

bool isIncludedIn	(	string	objId1,
		string	objId2
	)

function

Check if object with ID 'objId1' is included in object with ID 'objId2'.

Returns: false if there is no inclusion
true if object 1 is included in object 2 or is (geometrically) identical

Since: 1.5.0, 10 Dec 2014

◆ isModelReadOnly

var isModelReadOnly ( string modelID )

function

Returns whether the model is read-only or not, in case of an invalid model the result is undefined.

Parameters

modelID ID of model

Since: 3.5.0, 27 Aug 2024

◆ isPointIncludedIn

int isPointIncludedIn	(	double	x,
		double	y,
		double	z,
		string	objId,
		double	tol = `1.e-5`
	)

function

Check if point with given coordinates is included in object with ID 'objId'.

Parameters

x	: x coordinate of point
y	: y coordinate of point
z	: z coordinate of point
objId	: ID of object (mesh or composite)
tol	: numerical tolerance (The number of decimal places in tolerance should match with the decimal places in coordinate point values)

Returns: 1 - point is inside
0 - point is on border
-1 - point is outside
-2 - object not found

Since: 2.0.13, 05 May 2017

◆ mergeObjects

string mergeObjects	(	string	parentContainerId,
		var	idList,
		bool	skipClosed = `false`,
		bool	keepTransparency = `false`,
		bool	keepCommonProperties = `false`,
		bool	replaceParent = `false`
	)

function

Merge objects into a new one. The material of the resulting object is the material of the object with the largest surface area, or, if flag 'keepTransparency' is set, the transparent material.

Parameters

parentContainerId	Container that the result of the merge operation will be added to. If the option "replaceParent" is set, the input objects must be children of this container.
idList	IDs of objects to be merged. Can be passed as an array or a string (semicolon-separated).
skipClosed	Exclude closed meshes from merging.
keepTransparency	Keep transparent material, if any.
keepCommonProperties	Keep common properties of merged objects.
replaceParent	Replace parent container with merged object. Note that all children of the container must be merged in order for this to work.

Returns: ID of merged object, or one of the following codes in case of errors:
-1 No parent container with given ID or read-only
-2 No objects with given IDs, less than two objects or an object is read-only.
-3 Could not determine model of parent container.
-4 Parent could not be replaced. This could be the case if not all children are merged or the given parent is not the direct parent of the merged objects.
-5 No objects merged.

Since: 1.5.0, 05 Aug 2015; 2.8.3, 28 Jul 2021 : Added two parameters to align with GUI functionality.

◆ moveFile

bool moveFile	(	string	fnFrom,
		string	fnTo
	)

function

Move file 'fnFrom' to file 'fnTo'.

Since: 2.0.18, 31 jan 2018, jh

◆ openFile

bool openFile	(	string	filePath,
		string	encoding = `string()`
	)

function

Open a new file for writing. By default, local 8 bit encoding is used.
To change it, set encoding as optional second parameter.

Parameters

filePath	Name and path of the file to be opened. If no path is given, the current project's path will be used.
encoding	File encoding, such as "ISO 8859-1", "UTF-8", or "UTF-16". To write binary data, use "base64".

Returns: true if file was opened successfully, else false

Since: 1.3.0, 30 Oct 2013; 1.5.0, 23 Jul 2015 : added encoding parameter; 2.4.2, 01 Mar 2019 : changed behavior when no path is given (using project directory instead of application directory); 2.9.0, 06 Dec 2021 : added binary writing mode of base64 encoded data

◆ propertyScriptClearCache

void propertyScriptClearCache	(	string	domain = `"all"`,
		string	pname = `""`,
		string	datatype = `""`
	)

function

Clear cache of property scripts.
Calling this function without parameters will clear the entire cache.

Since: 2.5.0, 10 Mar 2019

◆ readCsvFile

object readCsvFile	(	string	filePath,
		string	delimiter = `";"`,
		string	encoding = `"Windows-1252"`
	)

function

Read text file in CSV format and return an array of all rows/cells.

Parameters

filePath	Name and path of file (if path is missing, file is expected in the project directory)
delimiter	Single character as delimiter of cells, most common are semicolon or tab.
encoding	File Encoding, by default "Windows-1252". Other options are "UTF-8", "UTF-16", "ISO 8859-1".

Returns: Object with key "csv", containing an array of rows, each with an array of values.

Example:

var lvFile = "tab-separated-text-file.txt";
var csv = desiteAPI.readCsvFile(lvFile, ";", "Windows-1252");
console.log(JSON.stringify(csv, 0, 4));

... returns something like:

{
    "csv": [
        [
            "RECID",
            "konfignr",
            "FORMULA",
            "TEXT"
        ],
        [
            "1132042",
            "1",
            "",
            "Schalung der Innen- und Aussenwand, \nals glatte Schalung aus Schalungsplatten gleicher Groesse.\nBetonflaeche moeglichst absatzfrei."
        ],
        [
            "1129053",
            "1",
            "(2.683)*2",
            "Ortbeton fuer Aufzugsunterfahrt aus Stahlbeton,\nals Normalbeton fuer Aussenbauteile nach DIN 1045-1;-2, C 25/30 \nExpositionsklasse XC2 nach Vorgabe Planer pruefen."
        ]
    ]
}

Since: 2.0.9, 17 Jan 2017; 3.2.3, 11 May 2023 : re-implemented to support multibyte characters, added optional encoding parameter

◆ readFileInChunks

var readFileInChunks	(	string	filePath,
		object	options
	)

function

Read a file and return its contents in chunks via a signal/callback.
Currently, only text files are supported.
The signal fileChunkReceived() will be emitted for each chunk, with its single string parameter containing the data.
After reading is finished, fileChunkReceived() will be emitted one last time with an empty string, indicating EOF (end of file).

Note that for small files (< 64 MB), you can use the more convenient readTextFile().

Parameters

filePath	Name and path of the file to read.
options	Object specifying `'encoding'` and `'bufferSizeInCharacters'`. Please see the example script below.

Small (but complete) usage example:

let fileContent = '';
desiteAPI.fileChunkReceived.connect(function onFileChunkReceived(fileChunk)
{
    if (fileChunk)
    {
        fileContent += fileChunk;
    }
    else
    {
        console.log('empty chunk received -> eof');
        desiteAPI.fileChunkReceived.disconnect(onFileChunkReceived);
    }
});
const options = {
    'encoding': 'UTF-8',                    // also supported: 'UTF-16', 'ISO 8859-1'
    'bufferSizeInCharacters' : 1024*1024    // equals 1 MB for single byte characters (unicode characters can span multiple bytes, though)
};
const retObj = desiteAPI.readFileInChunks('C:/Temp/Test/SomeLargeFile.txt', options);
console.log(JSON.stringify(retObj, 0, 4));
console.log('received data length overall: ' + fileContent.length);

Returns: Object containing error information, number of transferred chunks, and total transferred data. Example:
{
"chunks": 206,
"error": {
"code": 0,
"message": "OK"
},
"totalLength": 215939530
}

Since: 3.2.5, 22 Aug 2023

◆ readImageFile

string readImageFile	(	string	filename,
		string	targetFormat = `""`,
		bool	applyExifRotation = `false`
	)

function

Read image file and return a Base64-encoded string.
By default, this just encodes the raw input data into Base64, but you can optionally add image format conversion and Exif rotation.

Parameters

filename	Name of image file
targetFormat	Optionally specify "png", "jpg", "bmp" or "gif" for target format if you want a conversion. If you want to keep the original source format, this parameter can be omitted (or set to "").
applyExifRotation	If set to true, Exif data (if present in the source file) is evaluated to rotate the image. This will only work if an output format is specified (because otherwise, the raw input data will only be encoded, but not otherwise processed).

Returns: Base64-encoded image; empty string on error

Since: 2.0.16, 2017-10-18, ah; 2.7.2, 2020-12-08, ah : added Exif processing

◆ readTextFile

array< string > readTextFile	(	string	filename,
		bool	ignoreLineBreakesInDoubleQuotes = `false`,
		string	encoding = `string()`
	)

function

Read a text file and return its lines as an array of strings.

Parameters

filename	Name of file
ignoreLineBreakesInDoubleQuotes
encoding	File encoding, e.g. "UTF-8", "UTF16", "ISO 8859-1"

Returns: Array of strings containing each line of the file

const lines = desiteAPI.readTextFile(desiteAPI.getProjectDirectory () + '/WebForms/mat.csv');
for (let i = 0; i < lines.length; ++i)
{
    console.append(lines[i]);
}

Since: 1.3.6, 26 Apr 2014

◆ readTextFileAsString

string readTextFileAsString	(	string	filePath,
		string	encoding = `string()`
	)

function

Read a text file and return its complete content.

Parameters

filePath	Name and path of input file
encoding	File encoding, e.g. "UTF-8", "UTF16", "ISO 8859-1"

Returns: Complete content in one string

Since: 1.5.0, 23 Aug 2015

◆ recalculateActivityProject

int recalculateActivityProject	(	string	taskID = `string()`,
		bool	visibleOnly = `false`
	)

function

Recalculate projected dates of Activity Project.

Parameters

taskID	ID of root task. If ID is empty, all time schedules will be considered.
visibleOnly	Use visible tasks only

Returns: 1 - Ok
-1 - Error, Could not find task 'taskID'
-2 - Error, dependencies contain cycles
-3 - Error, failed to recalculate START/FINISH of summary tasks

Since: 2.8.6, 24 Feb 2022

◆ removeAllElementsFromColorScheme

var removeAllElementsFromColorScheme ( string colorSchemeID )

function

Remove all geometric elements from given color scheme.

Parameters

colorSchemeID ID of the color scheme

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.5.0, 26 Aug 2024

◆ removeAllLinkedObjects

int removeAllLinkedObjects ( string id )

function

Remove all linked objects from the element with the given ID.

Parameters

id	ID of element

Returns: 1 success
-1 element with given ID does not exist

Since: 1.0.17, 16 Jun 2012; 3.0.7, 13 Dec 2022 : Added reverse lookup

◆ removeAllRangesFromRegion

int removeAllRangesFromRegion	(	string	regionId,
		string	alignmentId = `string()`
	)

function

Remove all ranges from region.

Parameters

regionId	ID of region (will be returned if region is successfully added to an alignment)
alignmentId	ID of alignment. Optional parameter, if given, method is faster, because not all objects have to be searched

Returns: number of ranges removed on success
-1 alignment ID not found
-2 region ID not found

Since: 2.2.1, 20 apr 2018, sl

◆ removeAllRegionsFromAlignment

int removeAllRegionsFromAlignment ( string alignmentId )

function

Remove all regions from an alignment with given ID.

Returns: number of regions removed on success
-1 alignment ID not found

See also: addRegionToAlignment( string alignmentID, object setting )

Since: 2.2.1, 12 apr 2018, sl

◆ removeCalendar

int removeCalendar ( string calendarID )

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Removes a calendar. Note: The default calendar cannot be removed.

Parameters

calendarID ID of calendar

Returns: 1 Ok
-1 Could not find calendar
-2 Could not remove default calendar

Since: 2.9.2, 03 Mar 2022; 3.4.2, 10 May 2024 : deprecated

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

◆ removeCalendarException

int removeCalendarException	(	string	calendarID,
		var	date
	)

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Remove an exception from a calendar.

Parameters

calendarID	ID of the calendar
date	Date as ISO date string or Javascript Date(). When using Javascript Date, consider time differences (GMT).

Returns: 1 Ok
-1 Could not find calendar -2 Exception with given date does not exist

Since: 2.9.2, 03 Mar 2022; 3.4.2, 10 May 2024 : deprecated

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

◆ removeCalendarFromTask

int removeCalendarFromTask ( string taskID )

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Remove calendar from task. This will not affect inherited calendars.

Parameters

taskID ID of the task

Returns: 1 Ok
-1 Could not find task

Since: 2.8.5, 14 Oct 2021; 3.4.2, 10 May 2024 : deprecated

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

◆ removeCheckRule

int removeCheckRule	(	string	checkRunID,
		string	type,
		string	ruleID
	)

function

Remove check rule from check run. In case of attribute rules, the ID is required, else the (unique!) name or property type key. (TODO)

Parameters

checkRunID	ID of (model) check run
ruleTypeFilter	Type of check rule. If empty, all check rules will be removed. "ScriptRule" "AttributeRule" "UniquePattern"
ruleID	ID of check rule (pattern for UniquePattern check)

Returns

1 Ok
-1 Check run with given id not found
-2 Unknown rule type

Since: 2.9.3, 24 Mar 2022

◆ removeColorItem

var removeColorItem ( string colorItemID )

function

Remove the color item from the color scheme. This is only applicable to custom color schemes.

Parameters

colorItemID ID of the color item to remove

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.5.0, 10 Apr 2024

◆ removeColorScheme

var removeColorScheme ( string colorSchemeID )

function

Remove the color scheme from the project. This is only applicable to custom color schemes.

Parameters

colorSchemeID ID of the color scheme to remove

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.5.0, 10 Apr 2024

◆ removeElementsFromColorScheme

var removeElementsFromColorScheme	(	string	colorSchemeID,
		array< string >	elementIDs
	)

function

Remove geometric elements from given color scheme.

Parameters

colorSchemeID	ID of the color scheme
elementIDs	IDs of the geometric elements to remove

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.5.0, 10 Apr 2024

◆ removeFile

bool removeFile ( string filePath )

function

Remove a file

Parameters

filePath Name and path of file to be removed. If no path is given, the current project's path will be used.

Returns: true if file was removed successfully, else false

Since: 1.9.0, 24 jun 2016, mm

Remarks: 2.4.2, 01 mar 2019, ah : changed behavior when no path is given (using project directory instead of application directory)

◆ removeFromSelectionSetGeometry

int removeFromSelectionSetGeometry	(	string	setId,
		string	objectIDs
	)

function

Remove objects from selection set in domain 'geometry'.

Parameters

objectIDs String containing object IDs, separated by ';'.

Returns: 1 Ok
-1 Selection Set not found in domain 'geometry'
-2 Object(s) not found in domain 'geometry'

Since: 2.2.2, 28 aug 2018, jh

◆ removeLinkedObjects

int removeLinkedObjects	(	string	id,
		string	linkedIdList
	)

function

Remove links to a given list of objects from another object.

Returns: 1 success
-1 element with given ID does not exist

Since: 2.0.13, 1 may 2017, jh

◆ removeMaterial

var removeMaterial ( string materialID )

function

Remove the material from the project. This is only applicable to default materials, that are not assigned to a model.

Parameters

materialID ID of the material to remove

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.4.1, 08 Feb 2024

◆ removeModelReadOnly

var removeModelReadOnly ( string modelID )

function

Remove read-only state on model. This change will be permanent and might negatively affect the results of exports and re-imports.

Parameters

modelID ID of model

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.5.0, 27 Aug 2024

◆ removeObjectListFromTooltip

void removeObjectListFromTooltip	(	string	idList,
		string	tooltipname
	)

function

Removes the object list from tooltip.

Parameters

idList	List of objects
tooltipname	Name of the tooltip template

Since: 1.3.2, 28 mar 2014, jh

◆ removePropertyScript

int removePropertyScript	(	string	domain,
		string	pname,
		string	datatype
	)

function

Since: 2.5.0, 10 mar 2019, jh

◆ removePropertyTypeBookmark

bool removePropertyTypeBookmark ( string name )

function

Removes the given property type bookmark and returns 'true' on success.

Parameters

name	Name of the bookmark.

Since: 3.5.0, 12 mar 2025

◆ removePropertyTypeBookmarkByID

int removePropertyTypeBookmarkByID ( string id )

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Removes the given property type bookmark by ID.

Since: 2.2.4, 27 oct 2018

Deprecated:: Use removePropertyTypeBookmark() instead.

◆ removeRangeFromRegion

int removeRangeFromRegion	(	string	regionId,
		double	fromStation,
		double	toStation,
		string	alignmentId = `string()`
	)

function

Remove a range from a region. Example: Remove [110.0,300.0] from [0.0,350.0] => [0.0,110.0] + [300.0,350.0]

Parameters

regionId	ID of region (will be returned if region is successfully added to an alignment)
fromStation	Lower bound of range
toStation	Upper bound of range
alignmentId	ID of alignment. Optional parameter, if given, method is faster, because not all objects have to be searched

Returns: 1 success
-1 alignment ID not found
-2 region ID not found
-3 invalid range parameters

Since: 2.2.1, 20 apr 2018, sl

◆ removeRuleBasedLinks

int removeRuleBasedLinks ( string domainName )

function

Remove rule based object links for a given domain.

Parameters

domainName Name of domain

Returns: 1 ok
-1 error

Since: 2.6.1, 25 aug 2020, sl

◆ removeSelectionSet

bool removeSelectionSet ( string selsetID )

function

Remove selection set with given ID.

Returns: true if selection set could be removed, else false

Since: 2.5.1, 30 apr 2019, jh

◆ removeTaskRestrictions

int removeTaskRestrictions ( string taskID )

function

Remove task restriction from task.

Parameters

taskID ID of task

Returns: 1 Ok
-1 Could not find task

Since: 2.8.5, 14 Oct 2021

◆ removeVisualisation

int removeVisualisation ( string taskIDList )

function

Remove visualisation configuration from tasks.

Parameters

taskIDList IDs of task, separated by semicolon

Returns: 1 Ok
-1 Could not find any task

Since: 1.9.0, 16 jul 2016, jh

◆ resetDocumentMetaData

void resetDocumentMetaData ( string objId )

function

Forces the MetaDataThreadWorker to reread the meta data of document from URL.

Since: 1.9.0, 18 Jun 2016

◆ runCheck

int runCheck ( string checkRunID )

function

Run check in domain Model Check or Clash Detection.

Parameters

checkRunID ID of checkRun

Returns

1 Ok
-1 Check run with given id not found

Since: 2.9.0, 20 Aug 2021; 3.5.0 21 Nov 2024 Check runs can now always be executed, remove error code -2.

◆ setActiveColorScheme

var setActiveColorScheme ( string colorSchemeID )

function

Set active color scheme by ID. Empty string for no color scheme.

Parameters

colorSchemeID ID of the color scheme

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.5.0, 10 Apr 2024

◆ setAllPropertyTypesActive

int setAllPropertyTypesActive ( )

function

Set all property types active.

Since: 2.2.4, 27 oct 2018

◆ setAsComposite

int setAsComposite	(	string	id,
		bool	composite
	)

function

Change container with given ID to composite and vice versa.

Parameters

id	ID of container/composite
composite	true: set as composite, false: set as container

Returns: 1 Ok
0 Container is already of desired type
-1 No container with the given ID or read-only

Since: 2.4.1, 06 Feb 2019

◆ setAsOpening

int setAsOpening	(	string	objId,
		string	openingIDList
	)

function

Set list of objects as opening elements to a given object. Objects in lists which have openings will be skipped.

Parameters

objId	ID of object for which to set openings
openingIDList	Objects to set as openings

Returns: number of objects set as openings
-1 Could not find object, wrong type or read-only -2 Empty opening list

Since: 2.0.3, 10 Oct 2016

◆ setBoQBreakdownStructure

int setBoQBreakdownStructure	(	string	boqModelID,
		string	templateStr
	)

function

Set BoQ model structure by template string.

Parameters

boqModelID	ID of BoQ model
templateStr	Text with information about the BoQ structure like "1122PPPPI"

Returns: 1 - Ok
-1 - Could not find model
-2 - Wrong template

Since: 2.8.5, 27 Oct 2021

◆ setCalendar

int setCalendar	(	string	taskID,
		string	calendarID
	)

function

Set a calendar for a task.

Parameters

taskID	ID of the task
calendarID	ID of calendar

Returns: 1 Ok
-1 Could not find task
-2 Could not find calendar

Since: 2.8.5, 14 Oct 2021

◆ setCalendarOptions

int setCalendarOptions	(	string	calendarID,
		object	options
	)

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Set default options of calendar.

Parameters

calendarID ID of the calendar

Returns: 1 Ok
-1 Could not find calendar
-2 Invalid value passed in options

See also: object getCalendarOptions(string calendarID)

Since: 2.8.6, 28 Feb 2022; 3.4.2, 10 May 2024 : deprecated

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

◆ setCalendarWorkingTime

int setCalendarWorkingTime	(	string	calendarID,
		object	workingTime
	)

function

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

Set weekly working time. Existing values will be overwritten, invalid input data will be ignored.

Parameters

calendarID	ID of the calendar
workingTime	Object holding weekly working time.

Returns: 1 Ok
-1 Could not find calendar

See also: object getCalendarWorkingTime(string calendarID);

Since: 2.9.2, 03 Mar 2022; 3.4.2, 10 May 2024 : deprecated

Deprecated:: This method will be removed in future versions of VDC Manager and should not be used for new scripts anymore.

◆ setCheckActive

bool setCheckActive	(	string	checkRunID,
		bool	active
	)

function

Set check active or inactive

Parameters

checkRunID	ID of checkRun
active	true/false

Returns

true - success
false - check run with given id not found

See also: getCheckActive()

Since: 2.9.0, 20 Aug 2021

◆ setCheckFilterList

int setCheckFilterList	(	string	checkRunID,
		array< object >	filterList,
		bool	rightSet = `false`
	)

function

Set object filter for check- or clash run.

Parameters

checkRunID	ID of checkRun
filterList	Array holding filters, see below
rightSet	In case of clash runs, set filter for left (= false) or right (= true) object set

Returns

1 Ok
-1 Check run with given id not found

var filter = [
    {
        "propertyTypeKey": "cpName##xs:string",
        "pattern" : "ABC"
    },
    {
        "propertyTypeKey": "cpIsPartOfComposite##xs:boolean",
        "pattern" : false
    }
    ]
}

Since: 2.9.0, 01 Oct 2021

◆ setCheckItems

int setCheckItems	(	string	checkRunID,
		array< string >	elementIDist,
		bool	rightSet = `false`
	)

function

Explicitly set elements to be processed by check- or clash run. This can be done in addition to or instead of an object filter. Setting an empty list will clear the list of checked elements.

Parameters

checkRunID	ID of checkRun
elementIDList	Array holding IDs of elements/containers to be checked
rightSet	In case of clash runs, set filter for left (= false) or right (= true) object set

Returns

1 Ok
-1 Check run with given id not found

See also: int setCheckFilterList(string checkId, array< object > filterList, bool rightSet = false)

Since: 2.9.0, 14 Jan 2022

◆ setCheckOptions

int setCheckOptions	(	string	checkRunID,
		object	options
	)

function

Set options of a Model Check Run.

Parameters

checkRunID	ID of Check Run
options	Object holding options, see below

Returns

1 Ok
-1 Check run with given id not found

To get all available options, use

var id = '...';
var options = desiteAPI.getCheckOptions(id);
JSON.stringify(options);

Example:

var options = {
    "createFailed" : true,
    "createWarnings" : true,
    "createPassed" : true,
    "createIgnored" : false,
    "createUndefined" : false,
    "keepContainers" : false,
    "keepComposites" : true
}

See also: getCheckOptions()

Since: 2.9.0, 01 Oct 2021; 3.5.0, 24 Sept 2024 : This function is no longer used for Clash Detection settings. Use setClashDetectionSettings() instead.; 3.5.0, 19 Nov 2024 : Renamed and flipped behavior for checkObjectsOnly and checkPartsOfComposites to be aligned with clash run settings.

◆ setClashRunSettings

bool setClashRunSettings	(	string	clashRunID,
		var	settings
	)

function

Configure the settings of the passed in clash run.

Use getClashDetectionSettings() for a list of all parameters.

Parameters

clashRunID	ID of the clash run
settings	Settings to adjust for the given clash run

Example:

const clashRunID = "a6daca3e-9308-41f9-b1c9-89a33ddd9e8b";

desiteAPI.setClashRunSettings(clashRunID, { clashes: { checkEnabled: true, considerOnlyInclusions: "LeftIncludesRight" } });

Since: 3.5.0, 24 Sept 2024

◆ setColorItemData

var setColorItemData	(	string	colorItemID,
		var	colorItemData
	)

function

Change attributes for the passed in color item like the name or color.

Parameters

colorItemID	ID of the color item
colorItemData	color item data passed as an object

Example:

const colorItemID = "a6daca3e-9308-41f9-b1c9-89a33ddd9e8b";
let result = desiteAPI.setColorItemData(colorItemID, {
    name: "Blue",
    color: { r: 0, g: 0, b: 1, a: 0.3 },
    outline: true
});

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.5.0, 10 Apr 2024

◆ setColorSchemeData

var setColorSchemeData	(	string	colorSchemeID,
		var	colorSchemeData
	)

function

Change attributes for the passed in color scheme like the name.

Parameters

colorSchemeID	ID of the color scheme
colorSchemeData	color scheme data passed as an object

Example:

const colorSchemeID = "a6daca3e-9308-41f9-b1c9-89a33ddd9e8b";
let result = desiteAPI.setColorSchemeData(colorSchemeID, {
    name: "My Color Scheme",
    focused: false
});

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.5.0, 10 Apr 2024

◆ setLinkedObjects

int setLinkedObjects	(	string	elementID,
		string	IDList
	)

function

Create a link (relation) between objects.

Parameters

elementID	ID of element to the linked.object links. The element can be of any domain (like geometry, activity etc).
IDList	List of objects to be linked to. List must be a semicolon-separated string. Currently, only geometric elements are supported as link targets.

Returns: Number of objects linked.
-1 element 'eleID' does not exist

Since: 1.0.17, 16 jun 2012, jh

Remarks: last modified 2.4.2, 21 feb 2019, ah

◆ setMaterialData

var setMaterialData	(	string	materialID,
		var	materialData
	)

function

Change attributes for the passed in material like name or color. The name cannot be changed on materials assigned to a model, it is needed for proper re-mapping.

Parameters

materialID	ID of the material
materialData	material data passed as an object

Example #1:

const materialID = "a6daca3e-9308-41f9-b1c9-89a33ddd9e8b";
let result = desiteAPI.setMaterialData(materialID, {
    name: "Gray Window",
    ambient: { r: 0.5, g: 0.5, b: 0.5, a: 1 },
    diffuse: { r: 0.5, g: 0.5, b: 0.5, a: 1 },
    specular: { r: 1, g: 1, b: 1, a: 1 },
    transparency: 0.5,
    shininess: 0.5
});

Returns: result with error code 0 on success or > 0 on failure.
{
"code": 0,
"message": "OK"
}

Since: 3.4.1, 08 Feb 2024

◆ setPostProcessingCode

int setPostProcessingCode	(	string	checkRunID,
		string	code
	)

function

Set code for post processing

Parameters

checkRunID	ID of checkRun
code	Javascript code

Returns

1 Ok
-1 Check run with given id not found

Since: 2.9.2, 07 JAN 2022

◆ setProjectLongDescription

int setProjectLongDescription	(	string	s,
		bool	overwriteExisting = `false`
	)

function

Returns: 1 if successful, else -1

◆ setProjectNumber

int setProjectNumber	(	string	s,
		bool	overwriteExisting = `false`
	)

function

Returns: 1 if successful, else -1

◆ setProjectShortDescription

int setProjectShortDescription	(	string	s,
		bool	overwriteExisting = `false`
	)

function

Returns: 1 if successful, else -1

◆ setPropertyListAsJSON

void setPropertyListAsJSON	(	object	propmap,
		object	opt
	)

function

Set list of property values to objects.

Parameters

propmap List of properties as JSON object.

Example: Property List

{
    "domains": {
    "geometry": [{
        "ID": "Project Name::b1179c42-d5e9-4ae6-8e30-331aacaa30ec-00019c33",
        "name": "-",
        "3": "4"
    },
    {
        "ID": "Project Name::fa530fc1-55d3-4bbb-9cfb-daae0b400fc8-00019ce3",
        "name": "-",
        "3": "2"
    },
    {
        "ID": "Project Name::fa530fc1-55d3-4bbb-9cfb-daae0b400fc8-00019d0b",
        "name": "-",
        "3": "2"
    },
    {
        "ID": "Project Name::fa530fc1-55d3-4bbb-9cfb-daae0b400fc8-00019d54",
        "name": "-",
        "3": "4"
    }],
    "documents": [],
    "activities": [],
    "type": [],
    "boq": [],
    "cd": [],
    "pc": [],
    "res": []
    },
    "proptypes": {
        "3": {
        "name": "cp:STATUS",
        "type": "xs:long"
        }
    },
    "meta": {
        "created": "2018-08-03 14:24:04",
        "createdBy": "web@ceapoint.com"
    }
}

Parameters

opt	Options for setting property values. Target: 1: Database 2: Repo 3: Default HandleExisting: 0: overwrite 1: ignore

Example: Options

var opt = {
    "Prefix": "PRE:",
    "Suffix": "@2018-03-04",
    "Target": 2,
    "HandleExisting": 0
};

Since: 2.2

◆ setPropertyScriptBgColor

int setPropertyScriptBgColor	(	string	domain,
		string	pname,
		string	datatype,
		string	code
	)

function

Set code (background) of property script.

Returns: 0 Property not found
1 Ok
-1 Internal Error: Project not set

Since: 2.5.0, 06 mar 2019, jh

◆ setPropertyScriptCode

int setPropertyScriptCode	(	string	domain,
		string	pname,
		string	datatype,
		string	code
	)

function

Set code (value) of property script.

Returns: 0 Property not found
1 Ok
-1 Internal Error: Project not set

Since: 2.5.0, 06 mar 2019, jh

◆ setPropertyScriptFgColor

int setPropertyScriptFgColor	(	string	domain,
		string	pname,
		string	datatype,
		string	code
	)

function

Set code (foreground) of property script.

Returns: 0 Property not found
1 Ok
-1 Internal Error: Project not set

Since: 2.5.0, 06 mar 2019, jh

◆ setPropertyScriptOptions

int setPropertyScriptOptions	(	string	domain,
		string	pname,
		string	datatype,
		object	opt
	)

function

Returns: -1 : Error
0 : Property not fount, no changes
1 : Options set to property

options {
    "IsCached": true,
    "IsInheritable": true,
    "Unit": "m2",
    "DisplayName": "abc"
}

Since: 2.5.0, 10 Mar 2019

◆ setPropertyTypeActive

bool setPropertyTypeActive	(	string	pName,
		string	ptype,
		string	domain,
		bool	active
	)

function

Parameters

domain Domain(s) for which to set the active status, e.g. "geometry", "geometry;activities", "all"

Since: 2.6.1, 2020-08-26

◆ setPropertyTypeMetaData

int setPropertyTypeMetaData	(	string	pName,
		string	ptype,
		object	metadata
	)

function

Set meta data of property type such as display name and unit.

Parameters

pName	Name of property type
pType	Data type of property type
metadata	Object containing data to set

Returns: 1 OK
0 undefined
-1 could not find property type

Example:

{
    "DisplayName": "Volume",
    "Unit": "m3",
    "Domain": "geometry",
    "Inheritable": false
}

Since: 2.0.13, 13 May 2017; 2.8.7, 22 Mar 2022 : added option 'Inheritable'

◆ setPropertyValue

int setPropertyValue	(	string	objId,
		string	propName,
		string	propDataType,
		var	value
	)

function

A Property value is set in the Project Repository, DB or model (the lookup sequence for this is the same as when setting a Property via the GUI).
If the Property Type does not exist, it is created in the Project Repository.

To set a global property use objId = GlobalProject.

Parameters

objId	ID of element to set the property value to
propName	Name of the Property
propDataType	Data Type of the Property in XML notation (for example 'xs:string' or 'xs:long')
value	Property Value

Returns: Code:
1 - ok
0 - undefined
-1 - error, object not found
-2 - error, unknown data type
-3 - error, writing was rejected, could be read only or wrong format
-4 - error, illegal value type

See also: setPropertyValueDB(); createPropertyType()

Since: 1.0.17, 28 jun 2012, jh

Remarks: 2.0.6, 18 nov 2016, ah: added data type check; 2.8.5, 22 nov 2021, sl: added var type check

◆ setPropertyValueDB

int setPropertyValueDB	(	string	objIdList,
		string	propName,
		string	propDataType,
		string	propDomain,
		var	value,
		bool	createType = `true`
	)

function

A property is set in the database.

Only datatypes supported by the database are provided. In SQLite DBs, datatypes xs:int and xs:float are mapped to xs:long and xs:double accordingly.

Parameters

objIdList	: List of objects (objIDs separated by ';') which should be affected.
propDomain	: Domains that the object IDs will be looked up in and the property will be created for. Example: "geometry;activities". If empty, "geometry" is used.
createType	: If true (default), a property type will be created if not yet existing; if false, the operation will fail if the property type does not already exist

Returns: Code:
1 - Ok
0 - Undefined
-1 - Error: DB error
-2 - Error: At least one Object in 'objIdList' not found, or list was empty or too large (>5000 elements)
-3 - Error: Property Type locked
-4 - Error: Property Type not found
-5 - Error: Data type unknown or invalid
-6 - Error: Execution blocked

See also: int setPropertyValue()

Since: 1.0.18, 18 aug 2012, jh

Changed in 1.3.0, 30 jan 2014:
Extended signature by parameter 'propDomain'.

Remarks: 1.9.0, 1 apr 2016, ah: added optional parameter 'createType'; 2.0.6, 18 nov 2016, ah: added data type check and return value -5

◆ setTaskMode

int setTaskMode	(	string	taskID,
		int	mode
	)

function

Set Task Mode:

taskmodeManuallyScheduled = 1, taskmodeAutomaticallyScheduled = 2

To get task mode see class CoreAPI.

Returns: 1 - Ok
-1 - Could not find task 'taskID'
-2 - Could not set task mode

Since: 2.1.6, 15 mar 2018, jh

◆ setTaskRestrictions

int setTaskRestrictions	(	string	taskID,
		string	restrictionsID
	)

function

Set task restrictions for a task.

Parameters

taskID	ID of the task
restrictionsID	ID of task restrictions

Returns: 1 Ok
-1 Could not find task
-2 Could not find task restrictions

Since: 2.8.5, 14 Oct 2021

◆ setTempValue

void setTempValue	(	string	name,
		var	value
	)

function

Stores the value for property name as long as the project is not closed or reloaded. WebForm reload has no effect on it. No persistence. Information is lost when project is reloaded or the application is closed, even when the project is saved before.

Since: 2.4.1, 02 feb 2019, ar

◆ setVisualisationByID

int setVisualisationByID	(	string	taskIDList,
		string	visID
	)

function

Set visualisation configuration to task.

Parameters

taskIDList	IDs of task, separated by semicolon
visID	ID of visualisation

Returns: 1 Ok
-1 Could not find visualisation with given ID
-2 Could not get any task

Since: 1.9.0, 16 jul 2016, jh

◆ sortContainerByProperty

int sortContainerByProperty	(	string	containerId,
		string	propName,
		string	propType,
		bool	ascending = `true`,
		int	maxDepth = `0`
	)

function

Sort the elements of a container (any domain) by their property values of a given type.
The sorting is stable.

Parameters

containerId	Container to sort the children of
propName	Property Type name
propType	Property Type datatype
ascending	True by default, set to False for descending sort order
maxDepth	Hierarchy depth (meaning that sub-containers will be sorted, too). A value of 1 would only sort direct children. The default value of 0 will sort all levels.

Returns: 1 OK
-1 Given ID could not be resolved or object is not a container
-2 Invalid Property Type

Since: 2.9.1, 25 Jan 2022

◆ startProjectTransaction

int startProjectTransaction ( string domain = "geometry" )

function

Start transaction on project of given domain. Use this if you want to create many objects at once.

See also: endProjectTransaction()

Returns: number of currently open project transactions

Since: 2.2.1, 02 aug 2018, sl

◆ startTransaction

bool startTransaction ( )

function

Start database transaction.

Since: 1.0.18, 20 aug 2012, jh

◆ swapOrientationOfTriangles

int swapOrientationOfTriangles ( array< object > idList )

function

Swap orientation of triangles.

Parameters

idList List of mesh object IDs.

Returns: Number of objects affected

Since: 2.8.7, 28 Mar 2022

◆ synchronizationFinished

void synchronizationFinished ( bool success )

signal

Emitted when API call synchronizeDocumentContainer() finishes.

See also: synchronizeDocumentContainer()

Since: 2.9.1, 31 Jan 2022

◆ synchronizeDocumentContainer

int synchronizeDocumentContainer	(	string	containerId,
		bool	waitForCompletion = `false`
	)

function

Synchronizes a document container with the assigned local directory or webservice. A URL or RemoteURL must be set for the container which should be synchronized.
By default, the operation will run asynchronously.
The signal synchronizationFinished will be emitted on completion, with one bool parameter indicating success or failure.
The optional parameter 'waitForCompletion' can be used to block further script execution until the synchronization has finished. Note that if you call the function from a WebForms context, you will still need to add the await keyword for this to work.

Parameters

containerId	: ID of container to synchronize
waitForCompletion	: if true, blocks script execution until completed (default is false)

Returns: 1 : OK
0 : undefined
-1 : Element with ID 'containerId' could not be found.
-2 : Element with ID 'containerId' is not a container.
-3 : Container with ID 'containerId' is not properly set up for synching (local or remote URL missing or invalid).
-4 : Container could not be synchronized. Note that this code can only ever be returned when using the 'waitForCompletion' mode, because otherwise, the function will not wait for the actual sync result.

See also: synchronizationFinished();

Example (non-blocking):

desiteAPI.synchronizationFinished.connect(function onSyncFinished(success)
{
    console.log('synchronizeDocumentContainer() has finished ' + (success ? 'successfully' : 'with errors'));
    desiteAPI.synchronizationFinished.disconnect(onSyncFinished);
});
var retCode = desiteAPI.synchronizeDocumentContainer('af563d25-345a-4c11-8947-5017681f623d');
console.log(retCode);

Example (blocking):

var retCode = desiteAPI.synchronizeDocumentContainer('af563d25-345a-4c11-8947-5017681f623d', true);

console.log(retCode);

(Note that you can still connect to the synchronizationFinished signal as in the first example, but it usually won't be very useful.)

Since: 1.5.0, 06 Apr 2016; 2.9.1, 31 Jan 2022 : no longer blocking, emits signal on completion; 3.0.7, 17 Oct 2022 : re-introduced optional parameter for blocking script execution

◆ transformObject

int transformObject	(	string	objId,
		string	transformation
	)

function

Rotate, scale, translate object.

Parameters

objId	ID of object which should be transformed
transformation	scale, translate, rotate encoded as XML

Transformation:

<t>
<scale sx="1.0" sy="1.0" sz="1.0" />
<translate dx="10.0" dy="20.0" dz="30.0" />
<rotate x="2.0" y="1.0" z="2.0" m="0.5 0.5 0.0   0.5 0.0 0.5   0.0 0.0 1.0" />
</t>

Returns: 1 Ok
-1 Could not find object or read-only
-2 Not a geometric object

Since: 27 Dec 2013

◆ updateOOBB

int updateOOBB	(	var	objectIds,
		double	eps = `0.001`
	)

function

Update optimized, orientated bounding box (OOBB) of all given geometric objects. It will always be re-calculated.

Parameters

objectIds	IDs of objects to be affected (array or string, using ';' as separator)
eps	Threshold for optimization (default: 0.001)

Returns: Number of affected objects

Since: 1.5.0, 13 Jan 2015; 2.1.5, 19 Jan 2019 : extended to handle composites; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ updateOOBBxy

int updateOOBBxy	(	var	objectIds,
		double	eps = `0.001`
	)

function

Update optimized, orientated bounding box in xy-plane (OOBBxy) of all given geometric objects. It will always be re-calculated.

Parameters

objectIds	IDs of objects to be affected (array or string, using ';' as separator)
eps	Threshold for optimization (default: 0.001)

Returns: Number of affected objects

Since: 1.5.0, 13 Jan 2015; 2.1.5, 19 Jan 2019 : extended to handle composites; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ updateRuleBasedLinks

int updateRuleBasedLinks	(	string	domainName,
		bool	visibleOnly = `false`
	)

function

Update rule based object links for a given domain.

Parameters

domainName	Name of domain
visibleOnly	If true, only objects links of visible domain items will be updated (default: false)

Returns: 1 ok
-1 error

Since: 2.6.1, 25 aug 2020, sl

◆ updateSmartSets

int updateSmartSets ( array< string > smartSetIDs = array< string >() )

function

Update the Smart Sets with given IDs. If ID list is empty (default), all available Smart Sets will be updated.

Returns: number of updated sets (can be used to check if ID lookups were successful)

Since: 2.7.3, 2021-02-02, ah

◆ validateIfcCompatibiliy

int validateIfcCompatibiliy ( string bsModelID )

function

Checks if a building structure model is valid to be used by geometry export (must fulfill structural conditions).

Parameters

bsModelID ID of building structure model

Returns: 1 - Ok
-1 - Could not find model
-2 - Empty model
-3 - Only model root and groups of IFC types are allowed to be of type 'bsContainer'
-4 - Invalid type (not suited for parent element)
-5 - Maximum three nested elements of same type (bsSite/bsBuilding/bsBuildingStorey/bsSpace) are allowed

Since: 3.0.3, 04 Aug 2022

◆ writeFile

bool writeFile	(	string	filePath,
		string	content,
		string	encoding = `string()`
	)

function

Write a string as a whole to a file.

Parameters

filePath	Name and path of the file to be written. If no path is given, the current project's path will be used.
content	Data to be written to the file
encoding	File encoding, such as "ISO 8859-1", "UTF-8", or "UTF-16". To write binary data, use "base64" and encode the string accordingly.

Returns: true if file was written successfully, else false

Since: 1.3.0, 30 Oct 2013; 2.4.2, 01 Mar 2019 : changed behavior when no path is given (using project directory instead of application directory); 2.9.0, 06 Dec 2021 : added binary writing mode of base64 encoded data

◆ writePropertyValueDB

int writePropertyValueDB	(	string	objIdList,
		string	propName,
		string	propDataType,
		string	propDomain,
		var	value,
		bool	createType = `true`
	)

function

Write property value to database.

Other than setPropertyValueDB(), this method does not check if the objects given by objIdList exist in the project.

Returns: Code:
1 - Ok
0 - Undefined
-1 - Error: DB error
-2 - Error: list is too large (>5000 elements)
-3 - Error: Property Type locked
-4 - Error: Property Type not found
-5 - Error: Data type unknown or invalid
-6 - Error: execution blocked

Since: 2.0.16, 16 sep 2017, jh

◆ writeToFile

bool writeToFile ( string content )

function

Write text to an open file.

Parameters

content Content to be written

Returns: true - success,
false - file is not open

See also: openFile()

Since: 1.3.0, 30 Oct 2013

Functions

Signals

Function Documentation

◆ activatePropertyTypeBookmark

◆ addCalendarExceptions

◆ addCheckRule

◆ addColorItem

◆ addColorScheme

◆ addElementsToColorItem

◆ addMaterial

◆ addObjectListToTooltip

◆ addPropertyScript

◆ addPropertyTypeBookmark

◆ addRangeToRegion

◆ addRegionToAlignment

◆ addToSelectionSetGeometry

◆ appendToFile

◆ calcDistance

◆ calcOOBB

◆ calcOOBBxy

◆ calcPropertyValuesOverTime

◆ calculateDistance

◆ calcWorkInMinutes

◆ checkIfFileExists

◆ checkIntersection

◆ checkOverlapOBB

◆ clearCalendarExceptions

◆ clearCheckResults

◆ clearCheckRules

◆ closeFile

◆ copyFile

◆ createCalendar

◆ createContactObject

◆ createDirectory

◆ createModel

◆ createObject

DOMAIN ISSUES

◆ createObjectFromXml

DOMAIN GEOMETRY

DOMAIN ACTIVITIES

DOMAIN BUILDING STRUCTURE

DOMAIN DOCUMENTS

DOMAIN BoQ (Bill of Quantities)

DOMAIN TYPES

DOMAIN PROCESS COMPONENTS

DOMAIN CLASH DETECTION

DOMAIN MODEL CHECK

DOMAIN ISSUES

◆ createPropertyType

◆ createSelectionSet

◆ createSelectionSets

◆ createTimeSchedule

◆ csvClose

◆ csvHasNextLine

◆ csvNextLine

◆ csvOpen

◆ currentGeoPosition

◆ cutObject

◆ dbAssertTable

◆ dbCheckIn

◆ dbCheckOut

◆ dbClearCache

◆ dbClearCacheAll

◆ dbClose

◆ dbDeleteProperty

◆ dbEndQueryExec

◆ dbGetFilepath

◆ dbGetImmediateUpdate

◆ dbIsLocalCopy

◆ dbOpen

◆ dbQueryExec

◆ dbQueryLastError

◆ dbQueryNext

◆ dbQueryRecordset

◆ dbQueryValue

◆ dbSetImmediateUpdate

◆ deleteModel

◆ deleteObjects

◆ deleteProperty

◆ deletePropertyType