Custom Tools

Custom tools can be written and incorporated into the application. These tools are then available to the end users in the application.

Visibility Function is the code behind visibility of custom buttons for Design Tools, Map Tools, and Component Tools in the Designer XI application. This functionality is not applicable to Print Tools.

NOTE: This requires the feature flag Designer/WorkflowActionAndCustomToolVisibilityExpression.

New tools start with default Visibility Function code that always displays the custom tool button.

Use the Sample Visibility Functions drop-down to populate the code text box for any of the selected actions or to get a start on custom function code:

Approval Assignment displays the custom tool button when assignmentType equals Approval.
Design Custom Property lets you define a custom property value for the design that must be true for the button to display.
Draw Assignment displays the button when assignmentType is Draw.
Draw Assignment and Custom Property combines the Draw Assignment and Design Custom Property code samples into one.
Work Request Custom Property defines a custom property value for the work request that must be true for the button to display.

NOTE: The default three line Visibility Function code text box will expand as you enter lines of code.

While you can type directly in the Visibility Function text box, you may find the Test Function dialog an easier interface for editing. Use the Test Function button to open the Test Visibility Function dialog. On open, code in the Visibility Function text box will execute and return a Test Result. This dialog is a way to edit and test the Visibility Function. As you edit, keep in mind the function must return a Boolean result. The result indicates whether the custom tool button will display in the Designer XI application.

To test the code at any point, click the Evaluate Test Function button in the top right corner.

The Test Visibility Function dialog also includes function parameters (Work Request, Design, and Assignment) that you can view and use to test the resources or inputs. Testing allows you to verify the function code and confirm the button visibility works the way you intend.

When you are satisfied with the Visibility Function, close the Test Visibility Function dialog. Notice your edits now appear in the Visibility Function text box. Don’t forget to save your changes to update the function.

NOTE: If you make a mistake while editing the sample code in the Test Visibility Function dialog and want to revert to the original sample code, close the dialog and click Cancel on the Custom Tools tab.

Parameters

The following table describes the tool parameters that apply to all tool types (other parameters vary by tool type):

Parameter	Description
Applicable Domains	You can provide a tool for Gas designs, Electric designs, or both. Check the appropriate boxes for the desired domains.
Requires Connection	This means it is necessary to have an internet connection to use the custom tool. In other words, if the Uniform Resource Identifier (URI) Scheme and Base URI use https, an internet connection is required. If the designer is working with the application disconnected, the tool is still visible in the application (both in the Tasks drop-down menu or on the click wheel), but it is grayed out and cannot be clicked.
Defer Until Online	This is an additional choice when Requires Connection is checked. It is not available if Requires Connection is unchecked. This is available for Design Tools only. It is not available for Map Tools or Component Tools. Checking this option means the tool is available for the end user to execute while offline. However, the tool does not actually process until the application is back online. This is useful when the user wants to wait for a full design save sequence when the network is available. For example, if your company has a custom report that interfaces with your WMS, that report would require network connectivity to process. The users do not want to forget to run the report when back online. Thus, they can initiate it while offline as a part of their normal workflow, and the report runs when the network is available again.
Request Design Save	In order to ensure accurate results, a custom tool might need all edits saved prior to running. For example, if a designer just finished a few edits and now wants an updated cost estimate, the edits need to be saved for the cost estimate to be accurate. By checking this box, designers are asked if they would like to save prior to executing the custom tool. If the designer clicks Yes, a progress wheel appears, and the designer is able to use other parts of the application while waiting for the save and custom tool to complete.

Uniform Resource Identifier (URI) Scheme

The URI Scheme depends on what software is installed on the system. Thus, the possible schemes are too numerous to list. However, some common Windows URI schemes include:

bingmaps
file
http
https
mailto
ms-drive-to
ms-help
ms-settings-camera

Available Dynamic Properties by Tool Type

The table includes the dynamic properties that can be used when designing a custom tool. “Yes” means that property can be used for that tool type, and “No” means it is not available for that tool type.

Dynamic Property Descriptions:

[[component.attribute:***]] - The *** is any public property on the component, which is likely close to or the same as the value found in the component model API.
[[childCus]] - This tag is replaced by a delimited list using the delimiter defined in the "Child CU Delimiter" configuration field. Each item in the list is processed using the “Child CU Template” field. The “Child CU Template” field can also use dynamic properties, which include:
- [[cu.attribute:***]] - The *** is any public property that is available on the CU (for example, WMSCode or Description).
- [[quantity]] - The quantity of the CU.
[[cu.attribute:***]] - The *** is any public property that is available on the CU (for example, WMSCode or Description). When cu.attribute is used directly in the base URI/body, the custom tool assumes there is only a single CU associated with the component. If there are multiple CUs, the tool chooses the first CU assigned and uses it.
[[design.FilePath]] - The path on the disk to the local .DSR file.
[[design.id]] - The GUID of the design resource.
[[extent.json]] - Provides the current extent of the map (X min/ X max, Y min/ Y max, and spatial reference).
[[lat]] - WGS84 latitude of the clicked point on the map.
[[long]] - WGS84 longitude of the clicked point on the map.
[[pdf.id]] - The print tools generate a .pdf and store the file in the Design Storage Service as a "design attachment.” The "pdf.Id" is the attachment ID (GUID) which is required to retrieve the .pdf/attachment file.
[[spec.attribute:***]] - The *** is any public property on the spec that is related to the selected component, which is likely close to or the same as the value found in the component model API.
[[workRequest.Id]] - The GUID of the work request resource.
[[workRequest.Location]] - The Location field of the work request resource (usually the address).

Dynamic Property		Design Tools	Map Tools	Map Tools with No Design Open	Component Tools	Print Tools
[[component.attribute:***]]		No	No	No	Yes	No
[[childCus]]		No	No	No	Yes	No
	[[cu.attribute:***]]	No	No	No	Yes	No
	[[quantity]]	No	No	No	Yes	No
[[cu.attribute:***]]		No	No	No	Yes	No
[[design.FilePath]]		Yes	Yes	No	Yes	Yes
[[design.id]]		Yes	Yes	No	Yes	Yes
[[extent.json]]		No	Yes	Yes	Yes	No
[[lat]]		Yes	Yes	Yes	Yes	Yes
[[long]]		Yes	Yes	Yes	Yes	Yes
[[pdf.id]]		No	No	No	No	Yes
[[spec.attribute:***]]		No	No	No	Yes	No
[[workRequest.Id]]		Yes	Yes	No	Yes	Yes
[[workRequest.Location]]		Yes	Yes	No	Yes	Yes

Custom Tools and Flexible Virtualization

Flexible Virtualization is a Windows feature that provides enhanced security and stability to applications by isolating them to virtualized copies of the registry and file systems. A consequence of this enhanced security is that a custom tool that requires access to a file, such as the .DSR (see more information about file types in the topic File Directories and File Types on Client Machine), will not know the virtualized file path. Thus, the custom tool is unable to retrieve the file.

To circumvent this issue, whenever a designer executes a custom tool, the application copies the .DSR from the workflow folder to C:\Users\username\AppData\Local\Temp\SE. Knowing this, you can write custom tools to look for files in this directory.

When a designer executes a custom tool, the application deletes any files in this folder that have not been accessed in the past 24 hours.
Windows Disk Cleanup (or other utilities that delete temporary files) also deletes these files when executed.

Design Tools

Design Tools are presented to the end user on the My Work tab:

Map Tools

Map Tools are available when the end user right-clicks an empty space in the map:

Component Tools

Component Tools are presented to the user as they interact with a component on the map. These tools work against a single component, not multi-selected components.

Print Tools

Print Tools are available on the Print tab. If configured, they are added within a drop-down alongside the normal Print operation.

NOTE: Print Tools are available for Designer XI application version 11.4 or earlier. To create a different print workflow or tool in Designer XI version 11.5 and later, leverage a print workflow via Solution Center > Workflows.