Integration_Design_Documents.pdf
PDF 613 KB Posted
- Solicitation number
- 262835RM
- Issued by
- Sarasota County, Siesta Key CDP, Florida
About this file
This Integration Design Document describes the technical specifications for integrating Sarasota County's UMAX customer information and billing system with Online Utility Exchange (OUE), a customer credit rating and fraud prevention platform. The integration enables two primary functionalities: real-time customer credit rating requests during the move-in process to determine security deposit requirements, and incremental export of customer account data with balances to support OUE's credit rating calculations. The credit rating request process operates synchronously via REST API using JSON format with JWT token authentication, allowing Customer Service Representatives to obtain credit reports, fraud alerts, and ID verification services during new customer onboarding. The customer balance export process operates asynchronously through Secure File Transfer Protocol (SFTP), with Azure Data Factory transferring fixed-length ASCII files containing incremental customer data from UMAX to OUE's servers on a nightly basis. The integration design specifies that report IDs and binary deposit advisories will be saved on newly created customer records upon move-in completion, and CSR names will be included in all requests for traceability despite use of a service account for authentication.
The document indicates that Online Utility Exchange will retain reports for five years with archival after six months, requiring CSR contact with OUE for retrieval of archived reports thereafter. The integration applies exclusively to the move-in process, not to new connection processes, and includes optional functionality for preventing duplicate credit checks through pin lock configuration within UMAX. Data stream characteristics specify average and maximum message sizes as small, with message volume occurring approximately once per move-in event during business hours. Both data streams are configured as idempotent with logging enabled, and the file transfer process supports archive functionality, generation of empty files when zero records exist, and alerts for system monitoring. The document was finalized on March 31, 2026 as version 1.0 following go-live, with the design phase completed on October 4, 2025, and includes references to related integration mapping documents, enterprise solution architecture documentation, and functional requirements traceability matrices maintained in Sarasota County's SharePoint environment.
View the file
Other files
On GovTribe
Work with this file
- Download the original file
- Contacts named in this file
- Similar government files
- Ask GovTribe AI about this file
Text version
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 0 of 13
©Itineris - All Rights Reserved
Public
Integration Design Document UMAX®- Online Utility Exchange
4/10/2025
Attachment A - Integration Design Documents
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 1 of 13
©Itineris - All Rights Reserved Public
1 General
Table of Contents
1 General
1.1 Version history
1.2 Related documents and attachments
1.3 Input
1.4 Open topics
1.5 Approval & Signatures
2 Introduction
2.1 Management summary
2.2 Audience
2.3 Preconditions and assumptions
2.4 Requirements
3 Architecture
3.1 High level architecture
3.2 Applications
3.3 Data streams
4 Business processes
4.1 High-level processes
4.2 Customer credit rating report
4.2.1 Use cases
4.2.2 Supported scenarios
4.2.3 Process flow
4.2.4 Data streams involved
4.2.5 UMAX-OUEX-01-S – Customer credit rating report
4.3 Export customer balance data
4.3.1 Use cases
4.3.2 Supported scenarios
4.3.3 Process flow
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 2 of 13
4.3.4 Data streams involved
4.3.5 UMAX-OUEX-02-F – Export customer balance data
5 Communication paradigms
5.1 File transfer
5.1.1 File transfer from UMAX
5.2 Web service
1.1 Version history
Date Version Author Changes
7/30/2024 0.7.1 Chris Garland Initial document
8/30/2024 0.7.2 Gokul Kaliappan QA review
0.7.3
0.7 End of analysis phase version
0.8.1 First version design phase
0.8 End of design phase version
03/26/2025 0.9 Chris Garland End of development phase version
10/04/2025 1.0 Chris Garland Go-Live version
1.2 Related documents and attachments
ID Name Version Description
001 SCPU - IMD - UMAX – Online Utility
Exchange
Integration Mapping Document
002 SCPU - ESAD – Enterprise Solution
Architecture
Enterprise Solution Architecture Document
003 Functional Requirements Traceability Matrix
1.3 Input
ID Name Version Description
001 Analysis Workshop – 07/17/2024 Initial workshop
002 Confirmation Workshop – 09/12/2024 Confirmation workshop https://sarasotacounty.sharepoint.com/:x:/r/sites/PU-iCue/Business%20Process/SCPU%20Deliverable%2057%20-%20Functional%20Requirements%20Traceability%20Matrix%20-%20After%20Analysis.xlsm?d=w9e21382adb7449d29b3d4550292cfe95&csf=1&web=1
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 3 of 13
1.4 Open topics
ID ADI Open topic Status
1.5 Approval & Signatures
Function Name Date Signature
2 Introduction
2.1 Management summary
This document provides the design for the integration between UMAX® and ONLINE Utility Exchange (OUE). It describes the high-level business process flow, as well as the data streams and services that are herein involved.
The document is structured in a top-down approach, describing the business processes down to use cases and eventually the technical specifications for each data stream.
The integration between UMAX and ONLINE Utility Exchange enables the following functionalities & data exchanges:
• Request for customer credit rating report in UMAX Customer Service during move-in process.
• Share customer data to OUE to determine the credit rating.
ONLINE Utility Exchange
• OUE Provides customer credit rating report along with fraudulent alerts.
• They also provide ID Verification services and assist utilities with collections.
UMAX®
• UMAX requests for a customer credit rating report during the move-in process and calculates deposit charge based on the credit rating.
• The report number and result are saved on the newly created customer.
• UMAX provides customer data to ONLINE Utility Exchange
2.2 Audience
This document serves as a reference for project managers, analysts, consultants, IT staff members, architects, integration specialists, designers, and developers to provide insight in the design of the solution.
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 4 of 13
2.3 Preconditions and assumptions
ID Description
001 UMAX will store the report ID and binary advise of OUE on the newly created customers after the move-in process
002 Online requires traceability of the CSR handling the requests. They allow us to use a service account for the web service requests if the CSR information is included in the request
003 Online will keep the reports for 5 years. They will be archived after 6 months; at that point the CSR will have to call Online to retrieve the report.
004 The integration only applies to the move in process, the new connection process does not make use of
OUE.
005 OUE will provide the service to send the adverse action letter
006 There is an option to pin lock within UMAX configuration, to prevent multiple credit checks for the same customer.
2.4 Requirements
The requirements gathered from the RFP, analysis and design phase which were considered for the integration discussed in this document.
ID Origin Requirement
3 Architecture
3.1 High level architecture
The diagram shown below provides a high-level overview of the systems involved and the way they communicate with each other.
E X
O R
T
Customer Balances
CSV
Customer Balances
IM
P
O R
T
CSV
HTTP Response (Credit Rating Report)
A P
I
HTTP Request (Name/Address/...)
UMAX Integration layer
3.2 Applications
The applications shown in the table below are involved in this integration.
Application Short description
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 5 of 13
UMAX Back Office Customer Information System / Billing System
Online Utility Exchange Customer credit rating provider
3.3 Data streams
Data stream ID Data stream name Short description
UMAX-OUE-01-S Customer credit rating report Request for customer credit rating report during move-in process
UMAX-OUE-02-F Export customer balance data Provide customer data with balances to OUE
4 Business processes
In this section the high-level business processes are illustrated. The different interfaces are viewed in relation with the business process and further described.
4.1 High-level processes
Process Description
Customer credit rating report
Request for customer credit rating report during move-in process to access deposit requirements
Export customer balance data
Provide customer accounts and their balances. The information shared with OUE is used to generate credit ratings.
4.2 Customer credit rating report
A CSR initiates the move-in process in UMAX Customer Service. During the move-in process when the required customer data has been entered, a request will be sent to Online Utility Exchange for a credit rating. UMAX will process the response results from OUE to assess the deposit required.
The response will also contain a report ID which can be used to request the visual report from Online Utility
Exchange.
The response from OUE can also contain an alert that requires additional action from the CSR or OUE can request additional information like a freeze pin if the credit file is frozen. In these cases, additional information will be sent in the subsequent request to OUE.
The CSR can also request the visual report from OUE, this report will be shown in a separate tab in the browser.
If the move-in process is completed the report ID and binary deposit advise will be saved on the new customer.
Authentication with OUE will be done using a service account, for traceability the CSR name will always be included in the request.
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 6 of 13
4.2.1 Use cases
4.2.1.1 Credit Rating
The utility would request for customer credit rating and fraudulent alerts for accessing the deposit required by the customer to avail utility services.
4.2.2 Supported scenarios
The scenario’s supported by the interface.
Scenario Description Supported
001 Real-time or ad-hoc credit rating requests. Yes
002 Credit rating checks in UMAX Customer
Service move in
Yes
003 Credit rating checks in UMAX Back Office move in
Yes
004 Credit rating checks on the account party (for
Customer Self Service move in reviews)
Yes
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 7 of 13
4.2.3 Process flow
C u st o m e r cr e d it r a ti n g r e p o rt
1.2 Request for customer credit rating 1.3 Process Customer Credit rating request
1.7 Process additional information credit rating
request
1.4 Process credit rating response
1.10 Process customer credit rating report
Legend
Manual action
Automated action
Normal action
Optional action
1.1 CSR initiates Move-in process
1.5 CSR takes actions or requests for additional
information
1.6 Request for additional credit rating
information
1.8 Process additional credit rating response
1.11 Display customer credit rating report
1.9 Request customer credit rating report
json json json json
The following steps can be distinguished:
Step Description
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 8 of 13
1.1 Move in
The CSR initiates the move-in process in UMAX Customer Service.
1.2 Request customer credit rating
Request a customer credit rating from ONLINE Utility Exchange.
1.3 Process customer credit rating request
Online Utility Exchange calculates the customer credit rating and provides the results in a json format.
1.4 Process customer credit rating response
UMAX processes the response to determine if a deposit must be charged. The report ID and binary advise will be saved on the new customer if the move in process is finalized.
1.5 CSR takes actions or requests additional information [optional]
In case OUE returns with an alert, for example fraud alert, the CSR might need to act accordingly.
In case OUE comes back with the request for additional information, for example a frozen credit file will require the freeze pin to proceed, the CSR will need to provide the additional information.
1.6 Request additional customer credit rating[optional]
If more information was provided in the previous step a second attempt is made to request the credit rating json.
1.7 Process additional customer credit rating request [optional]
ONLINE Utility Exchange calculates the customer credit rating and provides the results in a json format.
1.8 Process additional customer credit rating response[optional]
UMAX processes the results to determine if a deposit must be charged. The report ID and binary advise will be saved on the new customer if the move in process is finalized.
1.9 Request customer credit rating report [optional]
The CSR can request the visual report from ONLINE Utility Exchange based on the report ID provided in the previously requested json.
1.10 Customer credit rating report [optional]
Online Utility Exchange retrieves the archived report which was previously created during step 1.3 or
1.7.
1.11 Display report [optional]
UMAX opens a second window with the HTML report.
4.2.4 Data streams involved
Data stream ID Data stream name Steps
UMAX-OUE-01-S Customer credit rating report 1.2 - 1.11
4.2.5 UMAX-OUE-01-S – Customer credit rating report
4.2.5.1 Communication paradigm
Paradigm item Description
Integration approach Web service
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 9 of 13
Exchange pattern Request / Response
Sequencing Synchronous
Authentication JWT Token
For additional details on web service calls, see section Web service
4.2.5.2 Data sources and targets
Type Application Role
Source UMAX Back Office Data provider
Target ONLINE utility exchange Data requestor
4.2.5.3 Web service format
Type Description
Type REST
Format JSON
Message field definition See Integration Mapping Document
4.2.5.4 Data stream characteristics
Type Description
Avg message size Small
Max message size Small
Avg message volume ~ once per move in
Max message volume ~ once per move in
Expected growth
Time window Business hours
Idempotent Yes
Logging Yes
4.3 Export customer balance data
Utility would provide customer accounts and their balances to ONLINE utility exchange with incremental data.
The information shared with OUE is used to generate credit ratings, which can be used to determine if a new customer needs to pay a deposit when moving in. OUE has access to information from multiple Customer
Information Systems, this is especially useful to have access to data for new customers with no data in UMAX.
4.3.1 Use cases
4.3.1.1 Calculate customer credit rating
In order to serve utility’s request for customer credit ratings, utility would be providing ONLINE utility exchange their customer data with balances on incremental basis. OUE will be using this data and other parameters to calculate customer credit ratings.
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 10 of 13
4.3.2 Supported scenarios
The scenario’s supported by the interface.
Scenario Description Supported
001 Single customer information export No
002 Bulk information export Yes
4.3.3 Process flow
E x p o rt c u st o m e r d a ta w it h b a la n ce s
1.1 Export customer information with balances 1.2 Import customer data and balances
1.3 Generate/update credit rating based latest
data
Legend
Manual action
Automated action
Normal action
Optional action csv
The following steps can be distinguished:
1.1 Export customer information with balances
UMAX exports customer data and balances in incremental
1.2 Import customer information with balances file
OUE imports the file for processing
1.3 OUE generates/update customer credit ratings
OUE keeps the customer credit rating updated with the latest changes
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 11 of 13
4.3.4 Data streams involved
Data stream ID Data stream name Steps
UMAX-OUE-02-F Export customer balance data 1.1
1.2
4.3.5 UMAX-OUE-02-F – Export customer balance data
4.3.5.1 Communication paradigm
Paradigm item Description
Integration approach File transfer
Exchange pattern Export / Import
Sequencing Asynchronous
For additional details on the file transfer, see section Error! Reference source not found.
4.3.5.2 Data sources and targets
Type Application Role
Source UMAX Back Office Data provider
Target ONLINE utility exchange Data requestor
Middleware UMAX Integration Layer Transport
4.3.5.3 File format
Type Description
Type File
Format fixed-length
Message intent Data file: Contains customer data with balances
Message content The file contains customer data with balances since the last export. It is an incremental data file
Message field definition See Integration Mapping Document
File name OUE_AccountHistory_<ExportDate>-<ExportTime>.txt’
File encoding ASCII
4.3.5.4 Data stream characteristics
Type Description
Avg message size Measurement in KB or MB or # records
Max message size Measurement in KB or MB or # records
Avg message volume Number of messages / days
Max message volume Number of messages / days
Expected growth
Time window Nightly/Weekend
Idempotent Yes / No
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 12 of 13
Multi-threaded (UMAX) No
Archive Yes
Generate empty file
(In case of 0 records)
Yes
Alerts If yes, provide details
5 Communication paradigms
This section provides an overview of how the data is communicated between the interfacing systems.
Please refer to the Enterprise Solution Architecture Document (ESAD) for additional details on the integration concepts. For more details on the individual components, refer to the Infrastructure Design Document.
5.1 File transfer
ONLINE Utility Exchange
SFTP
CLIENT
SFTP (22)
UMAX SFTP
DOWNLOAD
DATA FACTORY
UMAX File Share
FILE SERVER
SFTP
SERVER
Microsoft
Azure
HTTPS (433)
HTTPS (443)
SMB (445)
UPLOAD
DOWNLOAD
UPLOAD
5.1.1 File transfer from UMAX
1.1 UMAX to UMAX File Share
UMAX stores the file on the UMAX File Share
1.2 Azure Data Factory picks up the file
Based on a business event, Azure Data Factory starts its process by picking up the file
1.3 File is archived
If configured, ADF will first take a copy of the file and archive it on the predefined location
1.4 Upload to SFTP
Azure Data Factory uploads the file to the OUE SFTP
March 31, 2026 | SCPU - IDD - Online Utility Exchange v1.0 | page 13 of 13
1.5 ONLINE Utility Exchange downloads the file from their SFTP
5.2 Web service
Synchronous request/response
The request/response paradigm will be implemented in a synchronous way. In this solution this will result in web services called over the HTTPS-protocol. The answer is sent, and the connection is kept open until the response is delivered or a time-out occurs. When a timeout occurs, a message would be displayed to the user.
Authentication
A service account will be used to retrieve a JWT token which stays valid for 24 hours JWT for authentication.
Following parameters are used to retrieve a JWT token:
Parameter Description
OUE Company ID 9-digit company ID provided by Online Utility Exchange.
Username Username provided by Online Utility Exchange
Password Password association with the username.
Vendor Vendor ID provided by Online Utility Exchange
File details come from the government source that posted it. Updated .