Custom Tools
Custom tools can be written and then incorporated into the application. These tools are then available to the end users in the application.
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 in order 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 the application disconnected, the tool is still visible in the application (both in the Tasks drop-down 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 is dependent on what software is installed on the system. Thus, the possible schemes are too voluminous to list. However, some common Windows 10 provided 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:
-
[[quantity]] - The quantity of the CU.
-
[[cu.attribute:***]] - The *** is any public property that is available on the CU (for example, WMSCode or Description).
-
-
[[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/ Ymax, 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 Designer 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.
