Info: Special Variables (KB13022101) (DriveWorks Documentation)

Info: Special Variables

DriveWorks has built in variables known as Special Variables that can be used in rules.

Special Variables are found in the Rule Builder from the Quick Text drop down.

Available Special Variables are listed below:

Additional Folders

Name: DWAdditionalFolders

Will return the result of the rule applied to the Additional Folders parameter, see Specification Settings.

Examples

Rule	Meaning
DWAdditionalFolders	Will return the result of the rule applied to the Additional Folders parameter, e.g. DriveWorks\OtherDocs\|DriveWorks\OtherDrawings

Current Client Details

Name: DWCurrentClientDetails

Will return the user-agent string of the browser in use to the specification.

You can use the Current Client Details special variable in your own rules by using the Quick Text button on the Rules Builder.

Examples

Rule	Meaning
DWCurrentClientDetails	Will return the user-agent string Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Win64; x64; Trident/5.0), for a specification being run through Internet Explorer 9.0 (MSIE 9.0), on a Windows 7 - 64bit operating system (Windows NT 6.1; Win64; x64)

User-Agent Strings

User-agent strings return the following information from the browser:

Web browser (IE, Chrome, Firefox, etc.)
Web browser version (IE9.0, Firefox 9.0.1, etc.)
Operating systems (Windows 7, iOS, etc.)
Operating system type (32bit, 64bit)

A lot more information can be present in the user-agent string depending on the browser in use. Given the above criteria and the amount of current options available for each it would be impossible to list all variations of user-agent strings here.

More information can be found from the following external link:

MSDN article - Understanding user-agent strings.

Extracting the User-Agent String

Once you have the user-agent string you may have a specific requirement for a particular token used in the string.

To search the user agent string for the browser or version token could be very involved given the amount of possible variations. However, using the IsMatch function allows the use of regular expressions that will make this process more straightforward.

Please see the function IsMatch for examples of how this is accomplished.

Current Client XR Status

Name: DWCurrentClientXRStatus

This special Variable can be used to return specific information about the client's VR Setup/Configuration.

You can use the Current Client Details Special Variable in your own rules by using the Quick Text button on the Rules Builder.

Examples

Rule	Meaning
DWCurrentClientXRStatus	{"Name","Value";"Activity","None";"SupportsImmersive","False";"SupportsInline","False";"HasLeftControllerTracking","False";"HasRightControllerTracking","False"}

Current Client Languages

Name: DWCurrentClientLanguages

Will return a list of all of the current installed languages on the client machine that is accessing the DriveWorks project.

The list is returned as a table array.

You can use the Current Client Languages special variable in your own rules by using the Quick Text button on the Rules Builder.

Examples

Rule	Meaning
DWCurrentClientLanguages	Will result in the table array {"Languages";"en-US";"en-GB"}. Where the table has 1 field named "Languages" and 2 entries for the installed languages of "en-US" and "en-GB".

Rule

Meaning

DWCurrentClientLanguages

Will result in the table array {"Languages";"en-US";"en-GB"}.

Where the table has 1 field named "Languages" and 2 entries for the installed languages of "en-US" and "en-GB".

Current Macro Argument

Name: DWCurrentMacroArgument

The Current Macro Argument variable holds the result of an argument passed from the Macro Argument property of a Macro Button, the Run Macro or the Run Macro in a Loop tasks.

The result of this special variable can be used by using its name ( DWCurrentMacroArgument) in a rule.

The result can also be driven directly into a form control (see Drive Control Value) or a constant (see Drive Constant Value) by using Specification Macros.

Current Macro Caller

Name: DWCurrentMacroCaller

The Current Macro Caller variable holds the name of the Macro Button that has been clicked during specification.

To use the result of this special variable in a form control use the Drive Control Value task to drive the value into a user form control.

Current Macro Click Position

Name: DWCurrentMacroClickPosition

The Current Macro Click Position variable holds the result of the click position within the macro button.

The value returned is a pipe delimited string in the format X|Y, so the individual coordinates can be accessed with ListGetItem.

Examples

Rule	Meaning
ListGetItem(DWConstantCurrentPosition, 1)	Will return the X coordinate of the click position within the macro button.

The result of this special variable can be used by using its name ( DWCurrentMacroClickPosition) in a rule.

The result can also be driven directly into a form control (see Drive Control Value), a constant (see Drive Constant Value) or even a table by using Specification Macros.

Current Macro Event Argument

Name: DWCurrentMacroEventArgument

The Current Macro Event Argument variable stores information about the event that occurred on the control.

The following controls, support this Special Variable:

Check Box
Combo Box
List Box

When a change occurs to a supported control, and the On Change property is set, the following tabular data will be written to the variable:

Name	Value (Example Values given below)	Description
NewValue	True (for Check Box) Option A (for Combo or List Box)	The new value displayed in the control.
OldValue	False (for Check Box) Option B (for Combo or List Box)	The old value of the control.
Source	One of the following: Click from a mouse. Keyboard from a keyboard. Mouse Wheel from scrolling using the mouse wheel. ClearSelection as a result of the Clear Selection Allowed property being applied. Automatic/Rule as a result of a Override Rule property being applied.	The source from where the change came from.
Key	Return	Only available when the Source is Keyboard. The key on the keyboard that was pressed to result in the change.
Button	One of the following: Primary - when the button set as the primary button is clicked. Secondary - when the button set as the secondary button is clicked. Zoom - when the zoom button is clicked. Auxiliary - when any non-standard mouse button is clicked.	(Only available when the Source is Click)
ClickPositionX	50	Only available when the Source is Click. The position in the X, from the left of the control.
ClickPositionY	10	Only available when the Source is Click. The position in the Y, from the top of control.

Data can be extracted from this variable by using a Lookup function such as VLookup or DWVLookup.

For example:

Rule	Result	Description
VLookup("OldValue", DWCurrentMacroEventArgument, 2, FALSE)	True	Will look for the Name OldValue in the table constructed in the Current Macro Event Argument variable, and return the value from column 2 (the Value column). Don't use any function that uses an index (row, column number) to return a value. The order of these items may change in the future.

Current Release Loop Index

Name: DWCurrentReleaseLoopIndex

Will return the index of the current loop cycle for a Generation Task that has a loop enabled.

Examples

Rule	Meaning
DWCurrentReleaseLoopIndex	Will result in an index number (1 for example) representing the current loop index.

The value of this variable will display 0 in the rule builder.

Once a specification is run the first loop will be 1.

Current State ID

Name: DWCurrentStateId

This is a unique identifier of a state that is allocated when a state is created. This remains the same throughout the life of a state. If the state is renamed the State Id will not change.

Examples

Rule	Meaning
DWCurrentStateId	Will return the id of the current running state, e.g. 18a88d10-8d9c-4910-bfb8-06fa04ab3af2

Current State Name

Name: DWCurrentStateName

This has its value set every time a specification transitions to a running state.

If there is only one running state then this value will always be the name of the running state. In the default Specification Flow this will be 'Specify'.

Examples

Rule	Meaning
DWCurrentStateName	Will return the name of the current running state, e.g. Specify

Current User Display Name

Name: DWCurrentUserDisplayName

Will return the Display Name of the user logged into the DriveWorks application.

The Display Name for a user is created when applying Security Settings to the group.

Examples

Rule	Meaning
DWCurrentUserDisplayName	Will return the Display Name of the user logged into the DriveWorks application, e.g. Admin

When using this special variable and DriveWorks Autopilot is processing specifications, please ensure you have followed the steps in the article How To: Set Current User Special Variables When Using DriveWorks Autopilot.

Current User Email Address

Name: DWCurrentUserEmailAddress

Will return the Email Address of the user logged into the DriveWorks application.

The email address for a user is created when applying Security Settings to the group.

Examples

Rule	Meaning
DWCurrentUserEmailAddress	Will return the Email Address of the user logged into the DriveWorks application, e.g. john@company.com

Current User Name

Name: DWCurrentUserName

Will return the Login Name of the user logged into the DriveWorks application.

The Login Name for a user is created when applying Security Settings to the group.

Examples

Rule	Meaning
DWCurrentUserName	Will return the Login Name of the user logged into the DriveWorks application, e.g. Admin

Current User Password

Name: DWCurrentUserPassword

Will return the password for the user logged into the DriveWorks application.

The password for a user is created when applying Security Settings to the group.

Examples

Rule	Meaning
DWCurrentUserPassword	Will return the Password of the user logged into the DriveWorks application, e.g. Admin

Default Specification Folder

Name: DWSpecificationDefaultFolder

Returns the value of the Default Specification Folder setting, see General Settings.

Examples

Rule	Meaning
DWSpecificationDefaultFolder	Will return the value of the Default Specification Folder setting, e.g. D:\DriveWorks

Form Container Height

Name: DWFormContainerHeight

The special variable Form Container Height reports on the available height a form is being displayed in.

This is useful when designing user forms to adapt to changes in height on multiple devices.

Linking this special variable to the layout properties of form controls, user forms can dynamically adjust to suit the device the form is being viewed on.

Viewed in Form Design

When viewed in Form Design the special variable reports the height of the available Form Design area. This includes some padding within the form design area.

Viewed in a Browser

When a form is viewed in a browser (via DriveWorks Live) the available height of the browser is reported.

This does include some padding which is different depending on the theme or skin used.

Any factors controlling the container sizes (such as divs where the size is set) will be reported to this variable.

Form Container when viewed in Form Design	Form Container when viewed in a Browser

Examples

Rule	Meaning
DWFormContainerHeight	Will result in the height of the Form Design area while administering a project. Will result in the height of the browser area when viewed in DriveWorks Live.

Rule

Meaning

DWFormContainerHeight

Will result in the height of the Form Design area while administering a project.

Will result in the height of the browser area when viewed in DriveWorks Live.

Form Container Width

Name: DWFormContainerWidth

The special variable Form Container Width reports on the available width a form is being displayed in.

This is useful when designing user forms to adapt to changes in width on multiple devices.

Linking this special variable to the layout properties of form controls, user forms can dynamically adjust to suit the device the form is being viewed on.

Viewed in Form Design

When viewed in Form Design the special variable reports the width of the available Form Design area. This accounts for the Task Explorer on the left and the properties list on the right. It also includes some padding within the form design area.

Viewed in a Browser

When a form is viewed in a browser (via DriveWorks Live) the available width of the browser is reported.

This does include some padding which is different depending on the theme or skin used.

Any factors controlling the container sizes (such as divs where the size is set) will be reported to this variable.

Form Container when viewed in Form Design	Form Container when viewed in a Browser

Examples

Rule	Meaning
DWFormContainerWidth	Will result in the width of the Form Design area while administering a project. Will result in the width of the browser area when viewed in DriveWorks Live.

Rule

Meaning

DWFormContainerWidth

Will result in the width of the Form Design area while administering a project.

Will result in the width of the browser area when viewed in DriveWorks Live.

Initial Specification Id

Name: DWInitialSpecificationId

This reports the original (initial) specification id of a specification that has been copied.

Examples

Rule	Meaning
DWInitialSpecificationId	Will result in the original specification id once a specification has been copied, e.g. 1

Project Name

Name: DWProjectName

Returns the name of the Project.

Examples

Rule	Meaning
DWProjectName	Will return the name given to the project.

Revision Number

Name: DWRevisionNumber

Is an inbuilt number that begins at 1 when a new specification is created.

Each time an existing specification enters the edit transition (from the Pending or Completed* states of the default specification flow) the Revision Number will be incremented by 1.

* To edit existing specifications that are in the completed state of the default specification flow the setting "Allow existing specifications to be edited", available from General Settings, must be enabled.

This variable is triggered by the task Increment Revision Number.

Additionally the condition Setting: Can Edit Completed Specifications is applied to the Edit transition of the Completed state in the default specification flow.

Examples

Rule	Meaning
DWRevisionNumber	Will return 1 at the start of a new specification, and increment by 1 for each subsequent edit of the original specification.

Specification Full Path

Name: DWSpecificationFullPath

Returns the full path to the folder where the current specification will be stored.

This is a combination of the Default Specification Folder setting (see General Settings) and the rule applied to the Specification Path parameter (see Specification Settings).

Examples

Rule	Meaning
DWSpecificationFullPath	Will return the value of the Default Specification Folder setting and the rule applied to the Specification Path parameter, e.g. D:\DriveWorks\Specifications\Project 9999

Specification Id

Name: DWSpecificationId

Every time a project is run in DriveWorks Pro, it is allocated a guaranteed unique incrementing number called a specification id, which is combined with the name of the project to give the running project its specification name.

The Specification Id and Specification Name are used in DriveWorks Pro in various ways, e.g.:

Whenever a running project is finished, a folder is created which is named after the specification name in a folder called "Results" in the same folder as the project file.
By default, new models are created with the same name as their originals but suffixed with the specification name.

You can use the Specification Id and Specification Name in your own rules by using the Quick Text button on the Rules Builder.

The Specification Id and Specification Name are made available to the running project in two Special Variables called "DWSpecificationId" and "DWSpecification" respectively.

DWSpecificationID begins at 1 and has a range of approximately 2 billion.

Examples

Rule	Meaning
DWSpecificationId	Will result in 9999 while administering a project. Will result in the next available number once a specification has started, e.g. 1
TEXT(DWSpecificationID,"0000")	Will ensure the result contains at least 4 digits, e.g. 0001 This will NOT truncate the DWSpecificationID when the range goes above 9999 but will always include at least 4 digits.

Rule

Meaning

DWSpecificationId

Will result in 9999 while administering a project.

Will result in the next available number once a specification has started, e.g. 1

TEXT(DWSpecificationID,"0000")

Will ensure the result contains at least 4 digits, e.g. 0001

This will NOT truncate the DWSpecificationID when the range goes above 9999 but will always include at least 4 digits.

To reset the Specification Id please see the heading Reset Specification Id Pool in the Data Management Tool article Specification Information

Specification Name

Name: DWSpecification

Returns the result of the rule applied to the Specification name parameter (see Specification Settings).

Examples

Rule	Meaning
DWSpecification	Will return the result of the rule applied to the Specification name parameter.

Specification Parent Row Index

Name: DWParentRowIndex

To accompany the new embedded specifications functionality a new Special Variable, called Specification Parent Row Index (DWParentRowIndex) has been added.

This special variable reflects the position of each child specification in the parent specification's child specification control, and enables that position to be used in the child specification. The index will be automatically updated in each child specification when a child specification is added, deleted, copied, moved up and moved down.

The Embed child specification in Project Settings must be enabled.

Examples

Rule	Meaning
DWParentRowIndex	Will return 1 if the child specification is at the top of the list in the child specification list control. Will return 3 if the child specification is third in the list in the child specification list control.

Rule

Meaning

DWParentRowIndex

Will return 1 if the child specification is at the top of the list in the child specification list control.

Will return 3 if the child specification is third in the list in the child specification list control.

Specification Path

Name: DWSpecificationPath

Returns the result of the rule applied to the Specification Path parameter (see Specification Settings).

Examples

Rule	Meaning
DWSpecificationPath	Will return the result of the rule applied to the Specification Path parameter.

Specification Tags

Name: DWSpecificationTags

Returns the result of the rule applied to the Specification Tags parameter (see Specification Settings).

Examples

Rule	Meaning
DWSpecificationTags	Will return the result of the rule applied to the Specification Tags parameter.

Touchpoint Hit Position

Name: DWTouchPointHitPosition

The Touchpoint Hit Position variable holds the result of the absolute XYZ values and unit vector XYZ values within the 3D Preview.

The value returned is a pipe delimited string in the format X|Y|Z|nX|nY|nZ, so the individual coordinates can be accessed with ListGetItem.

Examples

Rule	Meaning
DWConstantHitPoint	198.5656\|-16.17453\|39.84293\|0.5224897\|0.8087573\|0.2852531
ListGetItem(DWConstantHitPoint, 1)	Will return the X coordinate (198.5656) of the click position within the 3D Preview.

The result of this special variable can be used by using its name ( DWTouchPointHitPosition) in a rule.

The result can also be driven directly into a form control (see Drive Control Value), a constant (see Drive Constant Value) or even a table by using Specification Macros.

DriveWorks Tech Tips Portal

Frame Control

The Frame control displays a box in which any user form, within the project, can be displayed, which can be used to create tabs which display different forms when clicked.

View all Tech Tips

Macro Button Selection

Works as a color picker. Select an item and assign it a color by using Macro Buttons to drive a value.

View all Tech Tips

DriveWorks Tech Tips Portal is available to DriveWorks Pro customers with an active subscription and support contract.

Tech Tips provide cut down projects that highlight specific functionality for faster and more effective learning.

To access the portal:

Go to https://my.driveworks.co.uk/learn/tech-tips/
Login with your DriveWorks Pro account credentials, if asked
Click the Visit Tech Tips Portal button for access

The portal provides a search facility, start typing the name of the Tech Tip (as indicated above) to display the Tip you require.

Knowledge Base Article Ref:	KB13022101

DriveWorks Pro 21 Info: Special Variables (KB13022101)