Integration Guide 001: How to configure a Web Adapter – ArcGIS Implementation

Use an ArcGIS Web Adapter to sync PowerClerk data to maps and features within ArcGIS.

1. The difference between the two ArcGIS Web Adapters
2. How to configure each Web Adapter
3. Setting up Automations to trigger each Web Adapter
4. ArcGIS Web Adapter-specific FAQs

Locating the ArcGIS Web Adapter

Anyone in a Role with the Define Connections privilege can navigate to the Web Adapter Configurations tab by opening the PROGRAM DESIGN menu and clicking on Connections:
 

Figure 1: PROGRAM DESIGN >> Connections

How to create an ArcGIS Web Adapter

There are two adapters involved in creating an ArcGIS Web Adapter, which in this example are called Add ArcGIS Lookup Lat/Long and Add ArcGIS Update Project on Map.
 
The first adapter, Add ArcGIS Lookup Lat/Long, converts addresses into coordinates in order to place PowerClerk projects on an ArcGIS map. The second adapter, Add ArcGIS Update Project on Map, passes chosen data fields from PowerClerk to ArcGIS.
 
To set up the first ArcGIS Web Adapter click the Add ArcGIS Lookup Lat/Long button on the Web Adapter Configurations tab:
 

Figure 2: Add ArcGIS Lookup Lat/Long button

 
Next, choose the Name, Input Fields, and Output Fields of your Web Adapter configuration.
 

Figure 3: Web Adapter configuration

 
To set up the second ArcGIS Web Adapter click the Add ArcGIS Update Project On Map button on the Web Adapter Configurations tab:
 

Figure 4: Add ArcGIS Update Project On Map button

 
Next, choose the Name, Input Properties, Input Fields and Output Fields of your Web Adapter configuration.
 
Setting the “Verify location on each call” field to “true” means that every time a project is updated it will be run through the ArcGIS Geocoder. However, one can set this field to “false” so that PowerClerk information will only be sent through the ArcGIS Geocoder the first time it is sent to ArcGIS. In which case the Address field in ArcGIS, for example, would NOT be updated if the field changes in PowerClerk.
 

Figure 5: Edit Configuration

 
Scroll down past the Input Fields in the “Edit Configuration” box to the Dynamic Input Fields section.
 

Figure 6: Dynamic Input Fields

 
For the PowerClerk Web Adapter and ArcGIS to properly communicate, the Field Name (database name) in ArcGIS needs to match the Dynamic Input Field name (see below image). Note that spaces in PowerClerk’s Web Adapter Configuration menu (Dynamic Input Fields > Field Name) [left picture] will be replaced by underscores in the ArcGIS’ Configure Attributes table Field Name [right picture].
 

Figure 7: Dynamic Input Field name

 
At least two Automations will now need to be set up in your Program, one for the ArcGIS Lookup Lat/Long Web Adapter and one for the ArcGIS Update Project On Map Web Adapter. Often only one automation is used for the former Web Adapter, while the latter automation is used for multiple status’ within the Workflow (for whichever point in the Workflow the ArcGIS map and/or PowerClerk need to be updated).
 
The ArcGIS Lookup Lat/Long Web Adapter could be set up, for example, as the project enters “Energy Storage – Installation Corrections Required”.
 

Figure 8: Automation for ArcGIS Lookup Lat/Long

 
An example configuration of the ArcGIS Lookup Lat/Long Web Adapter is shown below:

• Frequency : Every Time
• Fire Action : Always
• Action : Call Web Adapter
• Web Adapter Configuration : ArcGIS Lookup Lat/Long1
• Continue Processing : Continue

Figure 9: Edit ArcGIS Lookup Lat/Long Action Rule

 
The ArcGIS Update Project On Map Web Adapter could be set up, for example, as the project status enters Residential – Application Approved.
 

Figure 10: ArcGIS Lookup Lat/Long Automation

 
To replicate the above example, start by creating the Trigger:

• Trigger Type : Status
• Trigger Action : Status is entered

Figure 11: ArcGIS Lookup Lat/Long Automation Trigger

 
Then create the Action Rule that calls the Web Adapter:

• Frequency : Every Time
• Fire Action when the following Formula is true : Always
• Action : Call Web Adapter
• Select Web Adapter Configuration : Update Project on Map 1
• Continue Processing : Continue

Figure 12: ArcGIS Lookup Lat/Long Automation Trigger configuration

 
Figure 12b, below, shows the Web Adapter information that has been passed from PowerClerk to ArcGIS once the Automations have been set up. As you can see, the Project Number, Project Status, System Size (kW), Service Address, and Feature (blue square) have been populated onto the map. The Latitude, Longitude, and Address fields within the PowerClerk Web Adapter configuration have been translated into an exact location on the map via the ArcGIS geocoding service.
 

Figure 12b: ArcGIS Lookup example

FAQs

Q: What is the ArcGIS Web Adapter called in PowerClerk?

A: The Web Adapter is called "Add ArcGIS Update Project on Map", shown here:

Q: Where can I find the ArcGIS Web Adapter in PowerClerk?

A: Program Design > Automations > Web Adapter Configurations > Add ArcGIS Update Project on Map. Alternatively you may find this feature under Actions, if your program does not use Automations.

Q: Why isn’t the Web Adapter Configurations tab showing under the Actions/Automations section?

A: In order to configure Web Adapters a Clean Power Research Administrator must first enable the feature in your program.

Q: Does the "Verify location on each call" field mean that every time a project is updated it will be run through the ArcGIS Geocoder? At that point, the project already has a location, and therefore attributes should be the only fields that are updated.

A: Yes, setting the "Verify location on each call" field to "true" does mean that every time a project is updated it will be run through the ArcGIS Geocoder. One would want to set this value to “true” if, for example, the Address field (in PowerClerk) used to update the map ends up changing. At this point, the Geocoder is called to update the point on the map (in ArcGIS). One would also want to set this value to “true” if using a separate Dynamic Input Field in PowerClerk to populate an Address in ArcGIS. Otherwise the mapped location would not match the address listed in ArcGIS. However, one can set this field to "false" to prevent this scenario from occurring. In this example, the PowerClerk information will only be sent through the ArcGIS Geocoder the first time it is sent to ArcGIS. In which case the Address field in ArcGIS would NOT be updated if the field changes in PowerClerk.

Q: What are the "Object ID" and "Global ID" input fields found on the PowerClerk "Add Configuration" menu in the image shown below?

A: These fields reference the same fields found in ArcGIS. PowerClerk uses these IDs to match up with data in the ArcGIS database.

Q: Are the "Latitude" and "Longitude" coming from the ArcGIS Geocoder?

A: Yes, the "Latitude" and "Longitude" fields (shown in the image below) will be set in PowerClerk the first time the ArcGIS Web Adapter is called.

Q: How do I add more input fields for the ArcGIS Web Adapter in PowerClerk?

A: Click the "Add ArcGIS Update Project on Map" button and under this “Add Configuration” menu (image below) click the green "+" circle button under the Dynamic Input Fields section:

Q: Are the "Input Fields" for data going from PowerClerk to ArcGIS?

A: Correct; the "Input Fields" are what Clean Power Research recommends be designated in order to use the ArcGIS Web Adapter configuration.

Q: Do the "Input Fields" in the PowerClerk "Add Configuration" menu need to match the input fields found in ArcGIS?

A: Yes, the PowerClerk "Input Fields" should match the input fields found in ArcGIS. If, for example, you wanted to send over your own address field from PowerClerk to ArcGIS, one would use a Dynamic Input Field rather than the address Input Field found in the image above.

Q: What are the "Dynamic Input Fields"?

A: A "Dynamic Input Field" differs from an "Input Field" in that they are optional for the PowerClerk ArcGIS Web Adapter configuration. These fields are designed to allow for custom naming conventions.

Q: Do Dynamic Input Field names (found in the "Add Configuration" menu of PowerClerk) need to match ArcGIS or my distribution planning software field names?

A: The Dynamic Input Field names need to exactly match the ArcGIS field names.

Q: Can any of the “Built-in Fields” (Program Design > Data Fields > Built-in Fields) be used for the Web Adapter Configuration?

A: Yes, the following “Built-in Fields” can be used for the Web Adapter: Project_Number, Project_ID, Current_Status, Current_Status_Timestamp, OBJECTID, GlobalID.

Q: How are the “Built-in Fields” used in the configuration?

A: Notice that these fields are not found under “Input Fields” or “Dynamic Input Fields” on the Add Configuration Menu (Program Design > Automations > Web Adapter Configurations > Add [Web Adapter Name]. Instead, these fields are sent from PowerClerk, via the Web Adapter, to ArcGIS automatically (with no configuration needed). In other words, one just needs to configure the fields on the ArcGIS side and the data will be automatically transferred.

Q: Will the same ArcGIS Web Adapter that is set up in PowerClerk be used for each ArcGIS update?

A: Yes, for each ArcGIS update the same Web Adapter, configuration, and automations will be used.

Q: Will a separate ArcGIS Web Adapter be used when a PowerClerk project enters a status, especially if used to trigger a specific distribution planning analysis?

A: In many cases the same ArcGIS Web Adapter will be used. Anytime you want to send the same data to the ArcGIS map, the same configuration should be used. Doing so minimizes the Web Adapter configurations and ensures that stale data is updated. In other words, any time you want to send the same data to the same ArcGIS map, the same configuration should be used.

Q: Should the "database" or "alias" field name in ArcGIS be used to sync with PowerClerk?

A: For the PowerClerk Web Adapter and ArcGIS to properly communicate, the Field Name (database name) in ArcGIS needs to match the Dynamic Input Field name in the PowerClerk Web Adapter "Add Configuration" menu. Note that spaces will be replaced by underscores in the ArcGIS field name.

Q: What is a “Field Alias” in ArcGIS?

A: Per ArcGIS, the field alias is an alternative name for a field and can be more user-friendly than the actual name of the field. Field alias’ don’t have to adhere to limitations of the database. An example of this use case can be seen in the photo included in the above FAQ. The "ADDRESS_POSTAL_CODE" is setup to have an alias of "Zip". A recommended best-practice would be to make sure that anyone could connect the field alias to the field name. Doing so may avoid mistakes when communicating further down the workstream. Ultimately, the Alias is what users will see when interfacing with the maps in ArcGIS. The Field Name is what ArcGIS and PowerClerk will use to interface with each other.

Q: What is the process for getting a one-time initial load of every project that needs to be synced over to PowerClerk?

A: Projects can be loaded into PowerClerk by using the Import Projects feature.

Q: Am I able to configure the ArcGIS Web Adapter to remove projects from our ArcGIS if the status is Withdrawn?

A: If a project’s status changes within PowerClerk, a configuration of the ArcGIS Web Adapter may be set up so that the service is called and a project’s status within the ArcGIS data table is updated. Within ArcGIS a filter can be applied to the data table so that projects in the Withdrawn status are not displayed on the map. These projects cannot be removed from the data table.

Q: Where can I find information on how to acquire ArcGIS tokens?

A: Please follow this link.

Q: How does PowerClerk's ArcGIS Web Adapter work with tokens?

A: PowerClerk uses the token service to retrieve a token which is then used for both geocoding and for creating features. The three (3) web services (token, geocode, and feature) all need to be working together with the same set of credentials in order to easily integrate with PowerClerk.

Q: Which API does PowerClerk use for the ArcGIS Web Adapter -- REST or Python?

A: PowerClerk makes REST calls through C#.

Q: Can an ArcGIS Web Adapter be created in my PowerClerk Production and Test Environment's?

A: No, an ArcGIS Web Adapter can't be created in both programs because a duplicate Web Adapter would be created in Production when the Test Environment is committed (to Production).

Q: Can PowerClerk statuses be grouped together for ArcGIS?

A: Neither Milestones nor Formulas will accomplish this task. Instead, complete the status grouping within ArcGIS. Projects can be shown differently on the map based upon the status, but multiple statuses can be mapped to the same image.

Q: Can ArcGIS update PowerClerk with revised data (e.g. to replace stale circuit reconfiguration/retirement information)?

A: The PowerClerk Web Adapter makes a web service call into ArcGIS. However, there is no way for ArcGIS to return project data back on that call. However, if there is a way to trigger web service calls from ArcGIS then that call can be used to call the PowerClerk API and update the project data.

Have additional questions? Contact us to nominate your FAQ and help others find answers to your own questions concerning this feature.

Contribute To A PowerClerk Tutorial

Would you like to see a tutorial about a specific subject or contribute your experiences to share them with other PowerClerk Administrators? Contact the PowerClerk Support Team and propose a new tutorial at the PowerClerk Ticket System.

Create A Support Ticket

Not finding your answer here?  Submit a question to our support team at the PowerClerk Ticket System and leverage the PowerClerk team’s expertise.