Application & Process Automation

Getting Started
Authentication & Access
Agency and Program Information
Common Usage Scenarios
Create and Submit a Project
Add/Change Data in an Existing Project
Daily Polling for Project Changes
Using Custom IDs
API Method Reference
GetPrograms
URL Format
Response
XML Attributes
Sample Code
GetForms
URL Format
Response
Forms Attributes
AvailableInStatuses and LeadsToStatus
Status Attributes
Sample Code
GetFormSchema
V1 Response
V2 Response
Sample Code
GetProjects
V1 Response
V2 Response
Sample Code
GetProjectsByNumber
V1 Response
V2 Response
Sample Request
Sample Code
GetProjectsByData
Sample Request
Request XML Nodes and Attributes
V1 Response
V2 Response
CreateNewProject
Sample Response
Response XML Attributes
Sample Code
GetAllProjectData - Admin only
Sample Response
XML Attributes
Sample Code
GetProjectData
Sample Response
XML Attributes
Sample Code
SetProjectData
Sample Request
Request XML Attributes
Sample Response
Response XML Attributes
Sample Code
GetActiveAttachment
Sample Code
URL Format
GetAttachmentAsAdmin – Admin only
URL Format
SetProjectAttachment
Identifying attachment file types
URL Format
Sample Response
Response XML Attributes
Sample Code
SetAttachmentMetadata
Sample Request
Request XML Attributes
Sample Response
Response XML Attributes
Sample Code
GetAttachmentMetadata
URL Format
Sample Response
Response XML Attributes
Sample Code
SubmitProject
URL Format
Sample Response
Response XML Attributes
Sample Code
GetStatusList – Admin only
URL Format
Sample Response
Response XML Attributes
Sample Code
GetProjectStatusHistory – Admin only
URL Format
Sample Response
Response XML Attributes
Sample Code
SetProjectStatus – Admin only
URL Format
Sample Response
Response XML Attributes
Sample Code
GetExportProject – Admin only
URL Format
Sample Response
Response XML Attributes
Sample Code
Code Samples
EncodeAuthorizationHeader
MakeGetRequest
MakePostRequest
MakeGetFileRequest
PowerShell

Common Usage Scenarios

Below are a few common PowerClerk processes that we anticipate customers will complete using the API. You may find it useful
to run through the scenarios outlined here as a way to familiarize yourself with the API’s capabilities. The examples here
use the Clean Power Research Test Agency, but can be adapted to other agencies.

Create and Submit a Project

This example demonstrates how to use API calls to create a new project, populate one of the project’s forms with data and attachments, and then submit the form.
 

  1. Call GetPrograms with AgencyId = FN7635MW. In the response, note the ProgramId for the “Test Net Metering Program”.
     
    Sample call with CPR Test AgencyId = FN763MW:
    https://{BaseURL}/Programs?Agency=FN7635MW
     
  2. Call CreateNewProject with the ProgramId you just noted. In the response, note the ProjectId of the new project and the FormId for “Net Metering Application – TEST”.
     
    Sample call using ProgramId = 1HF29X4P:
    https://{BaseURL}/Programs/1HF29X4P/NewProject
     
  3. Call GetFormSchema with the FormId you just noted. Use the response to determine which DataFields and Attachments are required for this form, and note the corresponding DataFieldId and AttachmentId values.
     
    Sample call using ProgramId = 1HF29X4P and FormId = Q60TV2AF:
    https://{BaseURL}/Programs/1HF29X4P/Forms/Q60TV2AF/Schema
     
  4. Create an XML request payload to set data values for the required DataFields, using the DataFieldId values you just noted.
     
  5. Call SetProjectData with your request payload, using the ProjectId of the project you created earlier.
     
    Sample call using ProgramId = 1HF29X4P, ProjectId = AK6ZP5H9, FormId = Q60TV2AF:
    https://{BaseURL}/Programs/1HF29X4P/Projects/AK6ZP5H9/Forms/Q60TV2AF/Data
     
  6. Call SetProjectAttachment with the file you’d like to attach as the request payload. Use the AttachmentId you noted earlier.
     
    Sample call using ProgramId = 1HF29X4P, ProjectId = AK6ZP5H9, FormId = Q60TV2AF, AttachmentId = 3QX3VQ18:
    https://{BaseURL}/Programs/1HF29X4P/Projects/AK6ZP5H9/Forms/Q60TV2AF/Attachments/3QX3VQ18/Upload
     
  7. Call GetProjectData to view the DataField and Attachment values you’ve just set. Note the CanSubmit attribute in the Project element, which will be set to true if you’ve satisfied all the requirements to submit this form.
     
    Sample call using ProgramId = 1HF29X4P, ProjectId = AK6ZP5H9, FormId = Q60TV2AF:
    https://{BaseURL}/Programs/1HF29X4P/Projects/AK6ZP5H9/Forms/Q60TV2AF/Data
     
  8. If you’ve satisfied all the data requirements, call SubmitProject to submit this form for this project.
     
    Sample call using ProgramId = 1HF29X4P, ProjectId = AK6ZP5H9, FormId = Q60TV2AF:
    https://{BaseURL}/Programs/1HF29X4P/Projects/AK6ZP5H9/Forms/Q60TV2AF/Submit
     
  9. Use the SubmitProject XML response to verify that your form was submitted successfully and assigned a project number.

Add/Change Data in an Existing Project

This example demonstrates how to use API calls to add and edit data in an existing project.
 

  1. In the PowerClerk web interface, create a new project and add data to the Net Metering Application form. Save your changes.
     
  2. Call GetPrograms with AgencyId = FN7635MW. Take note of the ProgramId for the Test Net Metering Program.
     
    Sample call with CPR Test AgencyId = FN763MW:
    https://{BaseURL}/Programs?Agency=FN7635MW
     
  3. Call GetProjects with the ProgramId you just noted. In the XML response, find the project you just created and take note of its ProjectId.
     
    Sample call with ProgramId = 1HF29X4P:
    https://{BaseURL}/Programs/1HF29X4P/Projects
     
  4. Call GetProjectData with your ProjectId. Verify that the data you added in the web UI appears in the response. Take note of the DataFieldId values for the data fields you’d like to edit.
     
    Sample call using ProgramId = 1HF29X4P, ProjectId = AK6ZP5H9, FormId = Q60TV2AF:
    https://{BaseURL}/Programs/1HF29X4P/Projects/AK6ZP5H9/Forms/Q60TV2AF/Data
     
  5. Create an XML request payload to set or change the data in the Net Metering Application form. Use the DataFieldId values you noted earlier.
     
  6. Call SetProjectData with your request payload. Look at the response and verify that the data changes you made have been saved.
     
    Sample call using ProgramId = 1HF29X4P, ProjectId = AK6ZP5H9, FormId = Q60TV2AF:
    https://{BaseURL}/Programs/1HF29X4P/Projects/AK6ZP5H9/Forms/Q60TV2AF/Data
     
  7. In the web UI, open your project and verify that the data values have been changed by your API call.

Daily Polling for Project Changes

This example demonstrates how daily calls to the GetProject method can be used to keep track of projects that have been changed in the past 24 hours.
 

  1. Call GetPrograms with AgencyId = FN7635MW. In the response, note the ProgramId for the “Test Net Metering Program”.
     
    Sample call with CPR Test AgencyId = FN763MW:
    https://{BaseURL}/Programs?Agency=FN7635MW
     
  2. Call GetProjects with the ProgramId you just noted. In the response, find the ProjectsResponse element and note the value of the RequestTimestamp.
     
    Sample call with ProgramId = 1HF29X4P:
    https://{BaseURL}/Programs/1HF29X4P/Projects
     
  3. After a day, make another call to GetProjects. This time, include the “changed_since” parameter. Set the parameter value to the RequestTimestamp from the previous call. This will retrieve all the projects that have been changed since the previous call to GetProjects.
     
    In the response, note the value of RequestTimestamp.
     
    Sample call with ProgramId = 1HF29X4P and “changed_since” parameter:
    https://{BaseURL}/Programs/1HF29X4P?changed_since=2014-10-22T23:00:28.6263508%2B00:00
     
  4. On each subsequent day, make a call to GetProjects, using the value of the previous day’s RequestTimestamp as the value for the “changed_since” parameter. This will ensure continuous monitoring.
     

What’s Next?