Tracing Workflow Example
How to us ArcFM Web and Tracing Activities to create tracing capable workflows.
An overview of the technical architecture of ArcFM Web’s Workflow system is very useful for avoiding confusion and pitfalls during Workflow development. The diagram below captures the key components.
ArcFM Web Workflows always run on the server. The client may issue requests to trigger a workflow, and some workflows may need to transfer their execution state between the client and the server several times during their lifecycle, but all the heavy lifting takes place on the server. The workflow developer should keep this dynamic in mind, as there are potential pitfalls it can create. In order to transfer execution from client to server (or vice versa), ArcFM Web has to serialize the entire current state of the workflow and send it over the wire. Using scope in workflows will allow the developer control over this behavior so they do not transfer unneeded data. This control over scope allows the developer to avoid two key issues:
- Data size: If scope is not managed and all workflow variables are scoped to the top level, they will all serialize over the wire, whether the workflow really needs them or not. This can result in performance losses as objects are unnecessarily serialized, sent over the wire, and the deserialized.
- Data type: Not all types will be serializable. Those that are not will not be able to transfer between server and client. These types must be isolated via scoping to prevent exceptions during workflow execution.
ArcFM Web Tracing Activities
Schneider Electric has created workflow activities to facilitate the development of tracing enabled workflows. In order to utilize these, workflow developers will need to assure the necessary assemblies are present in their Workflow Designer directory structure (these assemblies are available in the ArcFM-Web-4.6.2.zip) For example:
C:\Program Files (x86)\SchneiderElectric\ArcFM Web\TestInstance462\Workflow Designer
This path may vary, depending on how your machine has been set up, but once the necessary assemblies have been placed, the activities will appear in the Workflow Designer:
ArcFM Server Tracing Server Object Extension (SOE)
ArcFM Server provides tracing capabilities via a Server Object Extension, or SOE. The SOE runs within ArcGIS Server, and is accessible via the same HTTP endpoints as standard ArcGIS Server functionality. It is this tool’s API that ArcFM Web Tracing Activities encapsulate.
The API for the tracing SOE can be viewed via the browser. For example:
This user interface provides access to the functionality of the SOE for testing purposes. Values can be plugged into this form allowing for verification the results match expectations for your data and configuration.
The parameters in the ElectricTracingActivity align closely to those of the SOE:
The previous section describes how the ElectricTraceActivity interacts with the ArcFM Server SOE. Now, you can begin parameterizing your workflow. Keep in mind the parameters exposed in the Workflow Designer expect VBScript expressions and you may see errors if the types the Designer expects are not the types it is being given.
A simple example of this is string literals, which will need to be wrapped in double quotes, thus making them a syntactically valid VBScript string expression.
With this in mind, here are some additional details on the parameters, and how they can be used.
- BaseUrl: The URL of the ArcGIS Service instance. In our example, the BaseURL would be http://<servername>/arcgis/rest/services/<mapservicename>/MapServer/>. Note that the SOE’s subpath is omitted. The activity will append this for us.
- TraceType: A string representation of the trace type. These vary for Electric, Gas and Water traces. An example for Electric would be “Downstream.”
- PhasesToTrace: A string representation of the phases to be considered for the trace. “Any” is the default.
- StartPoint: A JSON string representation of a MapPoint. The SOE begins its traces from a click point, and this parameter contains that click point.
- Tolerance: An integer value which tells the SOE how far from the StartPoint it can look for traceable features. Larger values will find features further from the StartPoint.
- DrawComplexEdges, IncludeEdges, IncludeJunctions, ReturnAttributes, ReturnGeometries: These are Boolean values which control the amount of data returned from the SOE.
- SpatialReference: A JSON string representation of the Spatial Reference in which results should be returned.
- EsriResult: The response from the SOE, deserialized into ESRI’s native types. Because many of the Out of the Box activities work against ESRI types, this will generally be the best way to get results.
- Result: The response from the SOE, deserialized into Schneider Electric’s types.
Debugging HTTP based applications is much easier with the aid of a tool like Fiddler, which allows individual calls to be inspected in detail. If ArcFM Web Tracing functionality is exercised while Fiddler is recording traffic, the parameters it is using can be inspected.
Here is a URLDecoded sample:
Using ElectricTraceActivity in a Workflow
With the input and output parameters understood, you can create a workflow which includes an ElectricTraceActivity. The URL captured above gives the values you can use for testing by plugging them into the ElectricTraceActivity:
This workflow has only one activity, but because the input parameters are configured, it can be tested in the Workflow Simulator and verified that Fiddler sees the request.
Once is has verified your request is going out and returning the expected results, those results can be used. Some of the Out of the Box activities that provide FeatureSet selection capability to the client can be used in this case.
As illustrated below, a ForEach activity is added which loops over the FeatureSets contained in esriResult, and uses the Out of the Box SelectFeatures activity to select each FeatureSet in turn. This will cause the data to appear in tabular form in your User Interface.
Registering a Workflow
In order to access a workflow from ArcFM Web, it has to be registered. This is done via the Essentials Manager, under the Workflows tab. Click Add Workflow and select your workflow from the filesystem. The Upload button is a handy way to push your workflow to the server without the hassle of navigating to the correct place on disk.
Invoke a Workflow from a Toolbar
After the workflow is registered, it needs to be run. A simple option for this is a Toolbar button.
Navigate to your Viewer in Essentials Manager and Edit it. Select the Toolbar tab, and use the Configured Toolbar section to add a button.
Don’t forget to “Apply Changes” and “Save Site.” You should now see your button in the viewer. If you click your button, you can test your workflow.
You may receive the “Alert” message below, it mentions data contracts and the message is an indication it is having serialization problems.
Since you can control scope, this error can be fixed. Add a ServerScope activity to the workflow and move the ElectricTraceActivity inside it. This explicitly tells the workflow it is expected to run the ElectricTraceActivity entirely on the server. It also provides a scope to associate your variables with. In this case, you move your “result” variable to the scope, preventing the engine from using that variable in the larger scope, and thus removing the need to serialize it down to the client.
You can then re-upload your workflow and retest.
Note that the tabular results at bottom of the User Interface are populated with numerous electrical features. You can click these rows to select the feature on the map.