PowerClerk Support Center

Program Design
Automations
Questions to Ask
Locating the Automations feature
How to create an Automation
Automation Triggers
Automation Action Rules
Validation Rules
Scheduled Triggers
Troubleshooting Automations
FAQs
Channels
Questions to ask yourself
Locating the Channels feature
What are Channels?
Types of Channels
Channel Type: Mark as Child
Channel Type: Make Successor
Channel Type: Create Related Project
Channel Type: Submit Related Project
Channel Type: Project Lookup
How to create a Channel
Channel Signals and Automations
FAQs
Communications
Questions to ask yourself
Locating the Communications feature
Creating Communication templates
Finding Data Tags
Bulk Communications via Data Import
Images in Communications
Project Attachments and Content Library Items
Smart Templates
Upgrading to Smart Templates
Upgrading when a Test Environment Exists
Broken Template Tags
Examples of Broken Template Tags
PowerClerk Bulk Email Communication Policy
FAQs
Connections
Questions to ask yourself
Locating the Connections feature
What are Connections
How to Create a Standard Web Adapter
Define Input and Output Fields
Connecting, Testing, and Enabling the Web Adapter
Creating a Standard Web Adapter Configuration
Utilizing Connections on PowerClerk
Maintaining and Editing the Web Adapter
Web Adapter Message Type Format
Supported Message Versions
Error Handling
Custom List Lookup
Create a Custom List Lookup
Utilizing Custom List Lookup
FAQs
Content Library
Questions to ask yourself
Locating the Content Library feature
Uploading content to the Content Library
Use with Communication Templates
Use for Front Page content
FAQs
Custom API IDs
Questions to Ask
Locating the Custom API IDs feature
How to edit a Custom API ID
FAQs
Data Fields
Questions to ask yourself
Locating the Data Fields feature
How to work with Data Fields
Custom Lists and Data Field Groups
Table form element
PV System + batteries element
FAQs
Deadlines
Questions to ask yourself
Locating the Deadlines feature
What are Deadlines
How to Create a Deadline
Deadline Automation Action Rules
Utilizing Project Admin Page for Deadlines
Communication Templates for Deadlines
Deadline Set/Satisfy Options
Program-Wide Deadline Actions
Reporting on Deadlines
Deadlines in Project List Columns
FAQs
Document Templates
Questions to ask yourself
Locating the Document Templates feature
How to define a new Template
How to define a new Merged Document
eSignatures
DocuSign template tags
Mapping eSignature tags
Smart Templates
FAQs
eSignature Envelopes
Questions to Ask
Locating the eSignature Feature
What are eSignature Envelopes?
eSignature Checklist: The Prerequisites to create a new Envelope
How to set up Advanced eSignature Envelopes Step-by-Step
How to add an eSignature Envelope to a form
eSignature Automation Trigger
Viewing Completed eSignature Envelopes
Resending eSignature Notifications
Canceling eSignatures
FAQs
Forms
Questions to ask yourself
Locating the Forms feature
How to create and edit Forms
Adding data fields
Configuring Forms
VersaForms
Sensitive Data Fields
FAQs
Formulas and Calculated Fields
Questions to ask yourself
Locating the Formulas feature
How to work with Formulas and Calculated Fields
Formula Data Dictionary
Dynamic Formula References
Rules of Formula References
Advanced Visibility Rules
Video Guides: Formulas
FAQs
Front Page
Questions to ask yourself
Locating the Front Page feature
How to edit the Front Page
FAQs
Incentive Design
Questions to ask yourself
Locating the Incentive Design feature
How to create and edit Incentive Designs
Incentive Options for One-Time Incentive Type
Incentive Design Options
FAQs
Milestones
Questions to ask yourself
Locating the Milestones feature
How to define a Milestone
FAQs
Project List Columns
Questions to ask yourself
Locating the Project List Columns feature
How to use Project List Columns
FAQs
Project Summary
Questions to ask yourself
Locating the Project Summary feature
How to edit the Project Summary
FAQs
Project Views
Questions to ask yourself
Locating the Project Views feature
How to edit Project Views
FAQs
Roles
Questions to ask yourself
Locating the Roles feature
How to create and edit a Role
Access Groups
Access Groups and Automations
Access Groups and Data Imports
Access Groups and Reports
FAQs
Workflow
Questions to ask yourself
Locating the Workflow feature
How to create and edit the Workflow
Transitions
Workflow Example Overview
FAQs
Administration
Business Days
Questions to ask yourself
Locating the Business Days feature
Setting up Business Days
FAQs
Dashboards
Questions to ask yourself
Locating the Dashboards feature
How to create widgets in your Dashboard
Other Dashboard Actions
Data Import
Questions to ask yourself
Locating the Data Import feature
Steps to Complete a Data Import
Data Import Configurations
Column Header Types
Automatic Data Imports via SFTP
FAQs
Duplicate Check
Questions to ask yourself
Locating the Duplicate Check feature
How to use Duplicate Checks
FAQs
Import Projects
Questions to ask yourself
Locating the Import Projects feature
How to Import From V2
FAQs
Operation Status
Questions to ask yourself
Locating the Operation Status feature
How to use the Operation Status feature
FAQs
Program Info
Project Inquiry
Locating the Project Inquiry feature
How to edit the Project Inquiry Settings
Automating Communications for Project Inquires
Inquiry Summary
Questions to ask yourself
Locating the Program Info feature
How to edit the Program Info menu
Notification Banners
Usage Info
FAQs
Program Statistics
Questions to ask yourself
Locating the Program Statistics feature
How to use Program Statistics
FAQs
Reports
Questions to ask yourself
Locating the Reports feature
How to setup Reports
Multi-instance reports
Sharing Reports
Integrate scheduled Reports
Cross-Program Reports
FAQs
Test Environment
Questions to ask yourself
Locating the Test Environment feature
How to setup a Test Environment
FAQs
User Administration
Questions to ask yourself
Locating the User Administration feature
How to work with User Administration
FAQs
Tools Menu
My Account
Questions to Ask
Locating the My Account feature
How to use the My Account feature
Setting up Multi-Factor Authentication
Missing, lost, or stolen mobile devices: resetting Multi-Factor Authentication
Disabling Multi-Factor Authentication
Recovery Guidelines for MFA Administrators
FAQs
FormSense
Questions to Ask
Locating the FormSense feature
How to use the FormSense feature
FAQs
Grant Access
Questions to Ask
Project Grants vs Broad Grants (i.e. "Grant Access")
Locating the Project Grant feature
Locating the Grant Access feature
How to use the Grant Access feature
FAQs
Integration Guides
ePayments
Questions to ask yourself
Locating the ePayments History feature
How to add ePayments
FAQ
PowerClerk API
Questions to Ask
What is the PowerClerk API?
What can the PowerClerk API do?
Integrating with the PowerClerk API
API Documentation for Developers
Single Sign On (SSO)
Questions to Ask
PowerClerk SSO Configuration
Azure AD Configuration (SAML)
Azure AD Configuration (OIDC)
Okta IDP Configuration (SAML)
SP Configuration
SSO for multiple programs
IDP Configuration Troubleshooting
FAQs
Integration Guide 001: How to configure a Web Adapter – ArcGIS Implementation
Integration Guide 002: How to configure Electric Power Research Institute’s (EPRI) DRIVE Connect software with PowerClerk
PowerClerk Video Guides
New User Video Guide
Setting up Business Days
Dashboards
FormSense
Edit Forms - Tutorial #1
Build A Formula
Edit Forms - Tutorial #2
Automation with Formulas in Action Rules
Configuring Forms
Formulas and Advanced Visibility Rules
Calculated Fields
Milestones
Project Summary
Setting up Roll-up Reports
Roles and User Administration
Visualize Workflows
ArcGIS
API
SFTP Automatic Data Import
Standard Web Adapter Setup
PowerClerk Program Launch
PowerClerk User Group Sessions (UGS)
Learning Management System (LMS)

Connections

Integrate access to custom web services with PowerClerk’s Connections functionality.

Front Page feature


Questions to ask yourself about Connections:

What is a Connection/Web Adapter?
What kind of Standard Web Adapters can be setup?
What external web service do I want to connect to through Connections?
What Message Formats can be sent with a Standard Web Adapter?
What is a Custom List Lookup?

Locating the Connections feature

Anyone in a Role with the Define Web Adapters privilege can create a Standard Web Adapter by opening the PROGRAM DESIGN menu and clicking on Connections. Please note: The Define Web Adapters privilege needs to be set by a CPR Admin, and you can request this privilege by contacting PowerClerk’s Support Team through the Ticket System.
 

Locating the Connections feature

Figure 1: ADMIN >> Connections

 
 

What are Connections?

Connections, also known as Web Adapters, allow PowerClerk to call utility-specific web services. A Web Adapter will work similar to an API call to a utility’s API service that occurs within PowerClerk and can be configured to be an automated process that can either fill in pieces of data (e.g., to lookup the customer’s address in a CIS system) or kick off processes in other systems (e.g. a “set meter request”).
 
Connections include Standard Web Adapters, Custom Web Adapters and Custom List Lookups. A Standard Web Adapter is a “self-service” web adapter builder for program designers. They are limited in message formats supported but can be adapted to any service endpoint changes. Standard Web Adapters do not support SOAP message formats. For more information on the message formats supported, please look below at Web Adapter Message Type Formats. A Custom Web Adapter will require the PowerClerk team to work in close conjuction with the utility and will support SOAP message types. For more information regarding Custom Web Adapters please create a ticket in the PowerClerk Ticket System. A Custom List Lookup Connection allows a user to validate or retrieve data from an existing Custom List within PowerClerk. For more information on how to set up and configure a Custom List Lookup, please see below under Create a Custom List Lookup.
 

PowerClerk’s Connections functionality enables you to define a set of parameters to integrate utility-specific web services. The process of creating a Connection consists of:

  • Utility admins will define the input/output data fields to use. The input fields will be the fields that PowerClerk sends to the web service and the outputs will be the fields that PowerClerk receives from the web service.
  • A Test UI that allows utility admins to configure the adapter based on what properties the adapter exposes (e.g., endpoint/URL pointing to the utility-specific web service). Please note: You can define separate URLs to switch between Production and Test Environments, and store authentication information, as well as which messaging format to use (XML or JSON).
  • Creating a Configuration, where you will be able to map the input/output variables to PowerClerk variables.

Once you have configured, tested, and enabled your web adapter there are two ways to use your new Web Adapter in your program:

  • On a Form with the Call Connection form element to create a button on a Form (to call the Web Adapter when a user clicks the button).
  • Via Automation to call the Web Adapter on status transitions or other Automation triggers, including automated retries if the targeted utility-specific web service is unreachable.

 

How to Create a Standard Web Adapter

Define the Input and Output Fields

When creating a Standard Web Adapter, you will need to specify the Input Fields (these fields will be sent from PowerClerk to the web service) and Output Fields (these fields will be sent from the web service back to PowerClerk).
 
For each Field, the following properties are defined:

  1. Name – the name of the field, which is used as a label in the UI
  2. DataType – the type of data that is passed in this Field. The DataType must be one of the following:
    • String – used for a Single Line Text field on a Form
    • Choice – used for a Drop-down List field or Multiple Choice field on a Form
    • Int64 – used for an Integer field on a Form
    • Decimal – used for a Decimal field on a Form
    • Boolean – used for a Check Box field on a Form
    • DateTime – used for a Date field on a Form
  3. IsRequired – Boolean indicating whether the program designer is required to provide a mapping for this Field when defining a Web Adapter Configuration.

Please Note: Defining the Input and Output fields will not create Data Fields on PowerClerk. This will need to be done on a Form before you can configure the Web Adapter to PowerClerk data fields.
 
See below for an example of the Edit Standard Web Adapter dialog to define input- and output fields in Connections after pressing the button New Standard Web Adapter:
 

Edit Web Adapter dialog

Figure 2: Edit Web Adapter dialog

 
 

Connecting, Testing, and Enabling the Web Adapter

Once the Standard Web Adapter has been created with the input and output fields defined the default status of the web adapter will be “Disabled”. After testing and configuring the connection to the utility-specific service’s endpoint URL, you can then select “Enable” for the Web Adapter to work within the PowerClerk program.
 

Testing new Web Adapter

Figure 4: Testing new Web Adapter

 
The sample configuration below demonstrates the settings which need to be defined to successfully connect to the utility-specific web service. Setting Support Email Alias allows users to define an email address to receive notifications and error messages in the context of this new web adapter. Connections also allow users to define a dedicated Production URL endpoint and Test Environment URL endpoint with unique authentication credentials for both. This will allow you to utilize your program’s Test Environment to facilitate testing Web Adapter changes separately from your ongoing Production Environment:
 

Connecting to utility-specific web service

Figure 5: Connecting to utility-specific web service

 
Please note: The Message Type format (XML or JSON) dictates the format in which to provide the web service’s response and cannot be mixed between both formats. More information regarding Message Type can be found below under Web Adapter Message Type Formats. More information on the Message Version will be found below under Supported Message Versions.

 
To test if the above configuration is properly set up to retrieve data from your web service, please go ahead and click on Save Properties and then enter sample data to test out the web service connection:
 

Testing utility-specific web service

Figure 5: Testing to utility-specific web service


 

Creating a Standard Web Adapter Configuration

Once the Standard Web Adapter has been tested and enabled, you will be able to create a Configuration by pressing the Create Configuration button. This configuration will be where you map the inputs and outputs defined to PowerClerk Data Fields.
 

Creating a Configuration

Figure 6a: Creating a Configuration
Mapping Back to PowerClerk

Figure 6b: Mapping Back to PowerClerk


 
Please Note: The Properties previously defined in the Testing phase will be auto input into the configuration. To edit those, you will need to go to the Standard Web Adapters Test page.
 

Utilizing Connections on PowerClerk

Once enabled and configured, a Connection/Standard Web Adapter will be able to be utilized on a Form or via an Automation.
 
Utilizing a Connection via Form
In a Form you will utilize the Call Connection Form element to create a button that will call the Web Adapter when a user clicks the button.
 

Call Connection Form Element

Figure 7: Call Connection Form Element

 
Utilizing a Connection via Automation
On an Automation, you can create an Action Rule with the action Call Connection and choose the Connection Configuration created to populate the data fields automatically.
 

Automation Call Connection Action Rule

Figure 8: Automation Call Connection Action Rule

 

Maintaining and Editing the Web Adapter

Clean Power Research will maintain input- and output logs for any request issued by a Web Adapter created in Connections. Please note that the Web Adapter testing dialog and Support Email Alias (with a valid email address) will provide the means to troubleshoot common connectivity issues and exceptions, such as:

  1. The remote server returned an error: (401) Unauthorized. – Root Cause: The credentials in the connectivity configuration dialog are invalid and need to be corrected or the utility-specific web service does not recognize the credentials as valid any longer.
  2. The remote server returned an error: (404) Not Found. – Root Cause: The endpoint URL for setting Production URL or Test URL are invalid and in need of a correction or the utility-specific web service is unavailable.
  3. The remote server returned an error: (500) Internal Server Error. – Root Cause: The utility-specific web service is not working properly and cannot provide a proper response to the Web Adapter request.

Please note: When encountering issues with your Standard Web Adapter configuration, you may also find additional error details on the Admin >> Operation Status page under the Failed Background Operations tab.
 
Once a Web Adapter has been used on a Form or in context of an Automation it cannot be altered in terms of input- or output fields and the proper way to re-use a prior Web Adapter configuration is to use the Copy functionality on the old Web Adapter to create a new version as shown below. This will create a new Web Adapter instance and allow you to proceed with necessary changes:
 

Copying a Web Adapter

Figure 9: Copying a Web Adapter

 

Web Adapter Message Type Formats

Web Adapter calls between PowerClerk and a utility-specific web service are made with a HTTP POST request to the endpoint URL that is associated with the web service. A client certificate is provided, and only HTTPS with TLS 1.2 is supported. For each Web Adapter, a serialization format for the message (for request and response) must be chosen as either XML or JSON. If XML is being used, then the message header will have “Content-Type” and “Accept” set to “application/xml”. If JSON is being used, then “application/json” will be used in the header instead. If username and password are needed for authentication to the server, then these values will be stored in the header through Basic Access Authentication (see https://en.wikipedia.org/wiki/Basic_access_authentication for details).
 
The message body is a collection of Name / Value pairs, where the Name is the specified as part of the Web Adapter Field, and the Value is the data associated with the PowerClerk DataField the Field is mapped to through configuration.
 
For XML, the message looks like the following.

<Fields>
    <Field Name="Account Number">123</Field>
    ...
</Fields>

For JSON, the message looks like the following. Note that for XML, values are always represented as strings, but for JSON, some values (such as numbers and Booleans) are not.

{
    "Account Number":"123",
    ...
}

The format for the Value depends on the DataType for the Field, as well as the type of serialization used.
 

  1. String or Choice DataType: The Value is simply the string data from PowerClerk. The only difference between these 2 DataTypes is that a Choice value must be a member of a pre-defined set of Strings in PowerClerk. Note that certain special characters will need to be escaped, following the requirements of the serialization format chosen. For XML the characters that must be escaped are documented at https://www.w3.org/TR/xml11/#sec-predefined-ent. The characters that must be escaped for JSON are documented at http://www.json.org/. For example, a Field with the Name “Sample String” and Value “`”@#$%^&*()<>\’” would be serialized as follows:
     
    XML
        <Field Name="Sample String">`"@#$%^&*()<>\'"</Field>
    JSON
        {"Sample String":"`\"@#$%^&*()<>\\'"}
     
  2. Int64 or Decimal DataType: The number numeric value is represented directly as a number in JSON, and as a String in XML. For example, the value 123 would be serialized as follows:
     
    XML
        <Field Name="Sample Integer">123</Field>
        <Field Name="Sample Decimal">123.0</Field>

    JSON
        {
            "Sample Integer":123
        }
        {
            "Sample Decimal":123.0
        }
  3. Boolean DataType: The value is represented directly as a lower-case Boolean value in JSON, and as a capitalized String in XML. For example:
    XML
        <Field Name="Sample Boolean">True</Field>
    JSON
        {"Sample Boolean":true}
     
  4. DateTime DataType: In both JSON and XML, the value is represented as a String in the ISO 8601 UTC format. For example:

     
    XML
        <Field Name="Sample DateTime">2019-10-24T00:00:00Z</Field>
    JSON
        {"Sample DateTime":"2019-10-24T00:00:00Z"}
     

A complete sample message with all the above data is shown below:
 
XML

<Fields>
    <Field Name="Sample String">`"@#$%^&*()<>\'"</Field>
    <Field Name="Sample Integer">123</Field>
    <Field Name="Sample Decimal">123.0</Field>
    <Field Name="Sample Boolean">True</Field>
    <Field Name="Sample DateTime">2019-10-24T00:00:00Z</Field>
</Fields>

JSON

{
    "Sample String":"`\"@#$%^&*()<>\\'",
    "Sample Integer":123,
    "Sample Decimal":123.0,
    "Sample Boolean":true,
    "Sample DateTime":"2019-10-24T00:00:00Z"
}


 

Supported Message Versions

When configuring Standard Web Adapters properties, there are two types of Message Versions to choose from, Fields only, and Fields and Project Information.
 
Message Format 1: Fields and Project Information
With this option, all input fields of your Standard Web adapter configuration are present within the Fields node, and the project meta data can be found in the Project Information node. The project information node contains the follwoing fields: ProjectNumber, ProjectPublicId, ProjectStatus, and ProjectStatusTimestamp.
 

Message Version

Figure 12: Message Version

 
Please Note: While testing the web adapter, the project information will appear null. Once the Connection has been configured and enabled on PowerClerk, Project Information will be filled in.
 
See below examples of the project information node in JSON and XML.
 
XML

<Request>
    <Fields>
        <Field Name="input1">Test Message</Field>
        <Field Name="input2">True</Field>
        <Field Name="input3">2.718281828</Field>
    </Fields>
    <ProjectInformation>
        <ProjectNumber>TEST-00001</ProjectNumber>
        <ProjectPublicId>ABCDEFGHIJKL</ProjectPublicId>
        <ProjectStatus>Test Status</ProjectStatus>
        <ProjectStatusTimestamp>2021-12-25T10:31:14</ProjectStatusTimestamp>
    </ProjectInformation>
</Request>

 
JSON

{
    "fields":
    {
        "input1": "Test Message",
        "input2": true,
        "input3": 2.718281828
    },
    "projectInformation":
    {
        "ProjectNumber": "TEST-00001",
        "ProjectPublicId": "ABCDEFGHIJKL",
        "ProjectStatus": "Test Status",
        "ProjectStatusTimestamp": "2021-12-25T10:31:14"
    }
}

 
 

Message Format 2: Fields only
The Fields Only option in the Message Version drop-down suppresses sending the Project Information node and does not delineate the Fields node separately. This means the messages will be simplified to the following format:
 
XML

<Request>
    <Field Name="input1">Test Message</Field>
    <Field Name="input2">True</Field>
    <Field Name="input3">2.718281828</Field>
</Request>

 
JSON

{
    "input1": "Test Message",
    "input2": true,
    "input3": 2.718281828
}


 

Error Handling

On the application level, PowerClerk’s Standard Web Adapter allows you to emit a descriptive error message instead of a regular result set. To emit an error please use the following keywords ServiceErrorMessage and ServiceErrorDetails which PowerClerk will interpret as follows:
 
Example error in XML:

<Fields>
    <Field Name="ServiceErrorMessage">This is an error</Field>
    <Field Name="ServiceErrorDetails">These are the error details.</Field>
</Fields>

 
Example error in JSON:

{
    "ServiceErrorMessage": "This is an error",
    "ServiceErrorDetails":  "These are the error details",
}

 
See below example screenshots on how this error would appear within the Test Connection dialog:
 

Error display

Figure 10: Error display

 
On an actual form this error will be displayed to the user encountering this error as follows:
 

Error display within a form

Figure 11: Error display within a form

 
 


 
 

Custom List Lookup

Standard Web Adapter versus Custom List Lookup

While a Standard Web Adapter can be used to retrieve information from a web service external to PowerClerk, creating a Custom List Lookup Connection allows to validate or retrieve data from an existing Custom List within PowerClerk. This kind of lookup can be beneficial if the use case scenario should not offer up the entire data available on the Custom List for selection by the applicant, but to retrieve data matches with the click of a button and then to further process the retrieved data in data fields outside of the originating Custom List:
 

Standard Web Adapter versus Custom List Lookup

Figure 13: Standard Web Adapter versus Custom List Lookup


 
 

Create a Custom List Lookup

Prior to creating a Custom List Lookup, a Custom List must be defined in PowerClerk. Setting up a Connection to a Custom List will allow validation and retrieval of output data from the Custom List based on the provided input. This lookup functionality can be helpful if the underlying Custom List has thousands of selections to choose from, which would become difficult to handle via a regular drop-down selection.
 
The results of a Connection to a Custom List Lookup can be populated into a variety of data fields present on the Form. These data fields do not need to be in proximity to the lookup button. Please Note: The configuration of the input and output fields for the Custom List is configured in the Connections page, while the configuration selection is done through the Automations page or on the Form Editor.

 

Edit Custom List Lookup

Figure 14: Edit Custom List Lookup

 
Once enabled, the Custom List Lookup Connection will become available for configuration. This will be configured in the Connections Page. You will be able to map the fields from the Custom List to PowerClerk Data Fields as shown below.
 

Create Custom List Configuration

Figure 15a: Create Custom List Configuration
Map Custom List Values to PowerClerk Values

Figure 15b: Map Custom List Values to PowerClerk Values


 
 

Utilizing the Custom List Lookup

Once enabled and configured, the Custom List Lookup will be able to be utilized on a Form or via an Automation. To learn more about how to utilize the Custom List Lookup Collection, read above, Utilizing Connections on PowerClerk.
 
The result in this example is populated with the respective data with the push of the Lookup EV Car button in the output fields as follows:
 

Custom List Lookup Results

Figure 16: Custom List Lookup Results

 

Video Guides

Web Adaptor

This video guide will demonstrate how to build a standard web adaptor that allows a customer to validate themselves.

 
A full list of all Video Guides can also be found here.

FAQs

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

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.