PowerClerk Support Center

Program Design
Automations
Questions to ask yourself
Locating the Automations feature
Creating an Automation
FAQs
Communication Templates
Questions to ask yourself
Locating the Communications feature
Creating Communication templates
Feature reference
FAQs
Deadlines
Questions to ask yourself
Locating the Deadlines feature
How to create Deadlines
Feature reference
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
Feature reference
FAQs
Roles
Questions to ask yourself
Locating the Roles feature
How to create and edit a Role
Feature reference
FAQs
Workflow
Questions to ask yourself
Locating the Workflow feature
How to create and edit the Workflow
Transitions
Changing a project's status
Feature reference
FAQs
Advanced Program Design
Channels
Locating the Channels feature
What are Channels?
Channels Checklist
3-Step Publishing Process
Channel Type A: Mark As Child
Channel Type B: Make Successor
Channel Type C and D: Create/Submit Related Project
Sending Signals
Document Templates
Questions to ask yourself
Locating the Document Templates feature
How to define a new Template
Feature reference
eSignatures
DocuSign template tags
Mapping eSignature tags
FAQs
Formulas and Calculated Fields
Questions to ask yourself
Locating the Formulas feature
How to create a Formula
Formula Data Dictionary
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 design an Incentive
Incentive Options
FAQs
Single Sign On (SSO)
Azure AD
Okta IDP Configuration
SP Configuration
PowerClerk API
Custom API IDs
FAQ
API Documentation for Developers
Application & Process Automation
Getting Started
Common Usage Scenarios
Using Custom IDs
API Method Reference
Code Samples
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
How to validate a Data Import
FAQs
Duplicate Check
Questions to ask yourself
Locating the Duplicate Check feature
How to use Duplicate Checks
FAQs
ePayments
Questions to ask yourself
Locating the ePayments History feature
How to add ePayments
FAQ
Import From V2
Questions to ask yourself
Locating the Import From V2 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
Questions to ask yourself
Locating the Program Info feature
How to edit the Program Info menu
Notification Banners
Billing 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
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
Web Adapter Factory
Questions to ask yourself
Locating the Web Adapter Factory
What are Web Adapters
Input and Output Fields
Connecting, Testing, and Enabling
Maintenance and Alterations
Web Adapter Message Format
FAQ
Program Reporting
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
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
FAQs
How to edit the Project Summary
Project Views
Questions to ask yourself
Locating the Project Views feature
How to edit Project Views
FAQs
Settings
My Account
Questions to ask yourself
Locating the My Account feature
How to use the My Account feature
Setting up Multi-Factor Authentication
MFA Recovery Guidelines
FAQs
FormSense
Questions to ask yourself
Locating the FormSense feature
How to use the FormSense feature
FAQs
Grant Access
Questions to ask yourself
Locating the Grant Access feature
How to Grant Access to users
FAQs
Integration Guides
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
Edit Forms - Tutorial #1
Edit Forms - Tutorial #2
Configuring Forms
FormSense
Build A Formula
Automation with Formulas in Action Rules
Formulas and Advanced Visibility Rules
Calculated Fields
Milestones
Project Summary
Roles and User Administration
Visualize Workflows
PowerClerk User Group Sessions (UGS)
PowerClerk Responsive Admin View

Web Adapter Factory

Integrate access to custom web services with Standard Web Adapters in PowerClerk’s Web Adapter Factory.

Front Page feature


Questions to ask yourself about your Web Adapter Factory:

What kind of Standard Web Adapters can be setup?
What external web service do I want to connect to through the Web Adapter Factory?
Do I have requirements beyond the Standard Web Adapter?

Locating the Web Adapter Factory feature

Anyone in a Role with the Define Web Adapters privilege can create a Standard Web Adapter by opening the ADMIN menu and clicking on Web Adapter Factory. 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 Web Adapter Factory feature

Figure 1: ADMIN >> Web Adapter Factory

 
 

What are Web Adapters?

Sometimes, it’s desirable in a Workflow to have automated processes fill in pieces of data (e.g. to lookup the customer’s address in a CIS system) or to kick off processes in other systems (e.g. a “set meter request”). That’s where Web Adapters come in – they allow PowerClerk to call utility-specific web services.
 
PowerClerk’s Web Adapter Factory enables you to define a set of configuration parameters to integrate utility-specific web services. It consists of:

  • Configuration UI to allow utility admins to pick which input/output data fields to use.
  • Configuration and Test UI to allow 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).

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 Web Service Call 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.

Web Adapter Factory

Input and Output Fields

When creating a user-defined Web Adapter, a collection of Input Fields (which are sent from PowerClerk to the web service) and Output Fields (which are sent from the web service back to PowerClerk) are specified. 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.

See below for an example of the Edit Web Adapter dialog to define input- and output fields in the Web Adapter Factory with the Create Web Adapter button:
 

Edit Web Adapter dialog

Figure 2: Edit Web Adapter dialog

 
 

Connecting, Testing, and Enabling

Once the new Web Adapter has been created and the input- and output fields have been defined it is still in a disabled state. You can now start configuring and testing the connection to the utility-specific service’s endpoint URL and enable the Web Adapter for usage within your PowerClerk program:
 

Testing new Web Adapter

Figure 3: 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. The Web Adapter Factory also allows users to define a dedicated endpoint URL and authentication credentials for your program’s Test Environment to facilitate testing Web Adapter changes separately from your ongoing Production Environment:
 

Connecting to utility-specific web service

Figure 4: 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.
 
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

 

Maintenance and Alterations

Clean Power Research will maintain input- and output logs for any request issued by a Web Adapter created in the Web Adapter Factory. 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.
 
When altering a Web Adapter created through the Web Adapter Factory, please note that 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 6: Copying a Web Adapter

 

Web Adapter Message Format

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">`"@#$%^&amp;*()&lt;&gt;\'</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">`"@#$%^&amp;*()&lt;&gt;\'</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"}

Video Guides

Would a video guide help to better explain Deadlines? Contact us and let us know.
 
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.