SeeClickFix 311 CRM provides a hosted integration with Trimble Unity Maintain for Service Requests, Work Orders, or both. Resident requests can be routed into Unity Maintain, while supported comments, images, and status changes can be synchronized between the systems.
Important Note:
The appropriate Unity Maintain API license(s) for this integration may require an additional purchase from Trimble. Confirm the organization's API access and licensing with Trimble. See Trimble's Licensing Fields and Assign Licensing documentation.
Requirements
A Unity Maintain configuration that uses Service Requests (SR), Work Orders (WO), or both.
A Unity Maintain API endpoint and an integration service account with permission to create and update Service Requests, Work Orders, or both, with the appropriate Unity Maintain API license(s).
Request and/or Work Order types, questions, status values, and any required custom fields that should be made available in SeeClickFix 311 CRM.
Features
Available capabilities depend on whether the integration is configured for Service Requests (SR), Work Orders (WO), or both. Some capabilities require additional configuration.
Syncing Categories
The integration can query Unity Maintain for public Service Request Problems or Work Order types and use them as request categories on SeeClickFix 311 CRM report forms.
Request categories are grouped into one or more customer-defined agencies, each with a geographic service area. These geographies are configured using polygon shapefiles uploaded to SeeClickFix 311 CRM.
This query runs on a schedule and can also be triggered on demand through the SeeClickFix 311 CRM internal system.
Syncing Questions and Answers (Service Requests Only)
For each request category synchronized with a Unity Maintain Service Request Problem, the integration queries Unity Maintain for a list of questions and answers.
Questions synchronized from the remote system are treated as Public in SeeClickFix 311 CRM unless the question text contains "email", "e-mail", or "phone". Questions containing those terms are marked Private.
If a secondary question should remain private in SeeClickFix 311 CRM, disable its automatic synchronization. A SeeClickFix 311 CRM Administrator must make that change.
Questions imported through automatic synchronization are always marked required in SeeClickFix 311 CRM.
This query runs on a schedule and can also be triggered on demand through the SeeClickFix 311 CRM internal system.
Address Lookup
When ArcGIS address validation is configured, the integration queries a customer-provided ArcGIS geocode service for an address based on the X/Y coordinates of the request before creating an SR or WO in Unity Maintain.
Submitting Requests
As requests are created in SeeClickFix 311 CRM, the integration submits them individually, on the fly, to Unity Maintain as a new SR or WO.
If an issue includes an image, the integration submits it to Unity Maintain as an SR or WO attachment.
Importing Requests (Service Requests Only)
Request importing is available for Service Requests only and requires additional configuration. When enabled, the integration periodically queries Unity Maintain for new SRs that originated there. This allows SeeClickFix 311 CRM applications, including the web portal and mobile apps, to display Unity Maintain SRs that did not originate in SeeClickFix 311 CRM.
The importer requires a standard polygon without cutouts for the agency geography. For example, a geography with state highways cut out of the polygon can cause importer errors.
Submitting Comments
As public comments are added in SeeClickFix 311 CRM, the integration submits them individually, on the fly, to Unity Maintain as SR or WO comments.
If a comment includes an image, the integration submits it to Unity Maintain as an SR or WO attachment.
Importing Comments
When remote comment importing is configured, the integration periodically queries Unity Maintain for comments added to the SR or WO and imports comments marked Make Public in Respond. See Trimble's Comment Fields documentation.
The Make Public control may need to be exposed through Style and included in the Respond profile used by staff. See Trimble's Respond Fields/Panels documentation.
Checking for Updates
The integration periodically queries Unity Maintain for changes to the SR or WO.
The integration closes the SeeClickFix 311 CRM issue when the Unity Maintain SR or WO has been closed.
Importing Images
When remote image importing is configured, SeeClickFix 311 CRM can import images attached to an SR or WO in Unity Maintain when the associated comment is marked Make Public.
The integration imports the comment and image into SeeClickFix 311 CRM as a public comment on the request.
Technical Requirements and Configuration
This section describes the information SeeClickFix 311 CRM requires to configure the Unity Maintain integration.
Important Note:
Enter sensitive information directly into the approved system. Do not send remote-system credentials to SeeClickFix 311 CRM staff. Direct implementation questions to the Implementation Manager or Support.
Terminology
Document Term | Description | Unity Maintain Term |
|---|---|---|
Local system | The SeeClickFix 311 CRM system. | N/A |
Client application | The remote or integrated system. | Unity Maintain |
Issue or local service request | The request information available in SeeClickFix 311 CRM. | N/A |
Remote service request | The corresponding request in Unity Maintain. | Service Request |
Issue ID | The primary key for the issue in SeeClickFix 311 CRM | N/A |
Remote service request ID | The primary key for the Unity Maintain Service Request | Request ID ( |
Service request type or request type | The classification assigned to the request, such as Pothole or Graffiti | Problem ( |
Status | The status of the issue in SeeClickFix 311 CRM | N/A |
Remote status | The status of the Unity Maintain Service Request | Stats ( |
Secondary questions | Additional questions associated with a request type | Questions associated with the selected Problem |
Service Endpoints and Network Access
SeeClickFix 311 CRM connects to the organization’s Unity Maintain environment through its API endpoint. CivicPlus recommends configuring and testing the integration in a separate sandbox environment before connecting it to production.
Unity Maintain endpoints commonly use the following formats:
Sandbox:
https://sandbox.maintain.unity.trimble.com/SANDBOX_<organization>Production:
https://maintain.unity.trimble.com/CLIENT_<organization>
The exact environment name is provided by Trimble or the organization’s Unity Maintain administrator.
Item | Description | Required? |
|---|---|---|
Test endpoint | API URL for the organization’s Unity Maintain sandbox environment. | When available |
Test API user | Dedicated integration account with access to the sandbox environment. | When available |
Test credential | Password, API key, or other credential assigned to the test API user. | When available |
Production endpoint | API URL for the organization’s production Unity Maintain environment. | Yes |
Production API user | Dedicated integration account with permissions to create and update Service Requests, Work Orders, or both. | Yes |
Production credential | Password, API key, or other credential assigned to the production API user. | Yes |
API Credentials
Important Note:
Do not send API credentials to CivicPlus staff through email, chat, or support-ticket comments.
Enter the endpoint and credentials directly in SeeClickFix 311 CRM:
Sign in to the appropriate SeeClickFix 311 CRM environment
Navigate to Manage Organization
Select Integrations
Enter the Unity Maintain endpoint and API-user credentials in the available fields
Trimble’s current connector documentation uses a dedicated API User and API Key. Existing Unity Maintain environments may use a different credential type. Use the credentials provided by the organization’s Unity Maintain administrator for its environment.
Network Access
SeeClickFix 311 CRM initiates connections to the configured Unity Maintain endpoint. The integration does not require Unity Maintain to call back into SeeClickFix 311 CRM.
Network requirements vary by environment. If the organization restricts access to its Unity Maintain environment through a firewall or other network controls, its IT staff must allow CivicPlus systems to reach the endpoint. Coordinate any customer-specific network requirements with the Implementation Manager.
Integration User
Use a dedicated, non-human integration account with permission to access the required Service Request and Work Order APIs. Do not reuse an employee’s personal Unity Maintain account.
The Unity Maintain employee record must have API Only enabled. API-only users cannot be used for interactive sign-in. See Trimble's Create a Username documentation.
GIS Information
SRID Projection
Provide the spatial reference information used by the remote system. SeeClickFix 311 CRM translates the request latitude and longitude to the configured remote projection before sending data to Unity Maintain.
Address Validation
By default, SeeClickFix 311 CRM passes latitude, longitude, and address fields when creating a service request. SeeClickFix 311 CRMM can also validate this information against a customer-provided ArcGIS geocode service associated with the remote system and send the ArcGIS result. Provide the ArcGIS geocode service to the Implementation Manager when applicable.
Service Request Types
Remote Request Types
SeeClickFix 311 CRM uses the Unity Maintain web services to define the service requests and secondary questions offered during reporting. Remote service requests must be defined so they are available to the integration's public request-type query.
Secondary Questions
SeeClickFix 311 CRM always collects a summary, description, and optional image when gathering service-request details. Secondary questions can be configured by request category to collect additional information.
Remote Secondary Questions
The integration supports text, yes-or-no, and date responses for secondary questions. Branching questions are not supported.
Email Attributes
SeeClickFix 311 CRM retains additional form-field descriptions and responses with the local service request and displays the information publicly. If the question field contains "email", the question and answer are not displayed publicly, which helps prevent accidental disclosure of private email addresses.
Required Attributes
SeeClickFix 311 CRM enforces the required attribute on questions and ensures the response contains text other than whitespace.
Question Order
SeeClickFix 311 CRM displays questions in the order specified by the remote question-sequence property.
Service Request Synchronization
The purpose of the integration is to keep the local SeeClickFix 311 CRM service request synchronized with the remote Unity Maintain service request. When a remote service request is created from SeeClickFix 311 CRM, the integration creates a matching remote record. When the remote request is completed, the integration updates the SeeClickFix request to reflect the change.
Local Status | Remote Status | Notes |
|---|---|---|
Open | N/A | The request was reported to SeeClickFix 311 CRM but has not yet been accepted by the remote system. |
Acknowledged | Open | The request has been accepted by the remote system. |
Closed | Closed | The request has been closed. |
Archived | Closed | The request has been closed for more than two weeks. |
Service Request Creation
Issue Field Mapping
The following mappings have been confirmed through the Unity Maintain Service Request schema and SeeClickFix integration testing. The exact values sent may depend on the request and the organization’s Unity Maintain configuration.
SeeClickFix 311 CRM Information | Unity Maintain Field | Notes |
|---|---|---|
Unity Maintain request ID | RequestId | Unity Maintain’s identifier for the Service Request. |
SeeClickFix issue ID | OtherSystemId | Preserves the SeeClickFix issue identifier for correlation between systems. |
Request category | ProblemSid and ProblemCode | Identify the Unity Maintain Problem associated with the request. |
Summary | Description | Contains the SeeClickFix request summary. |
Summary and description | Details | Contains the combined request summary and description. |
Latitude | SRY | Converted to the configured remote projection before submission. |
Longitude | SRX | Converted to the configured remote projection before submission. |
Address | ProbAddress | Unity Maintain also provides separate fields for city, state, ZIP code, apartment number, landmark, district, and location. |
Source application | InitiatedByApp | Identifies SeeClickFix as the source application. |
Reporter identity | Customer-specific | The validated response does not identify a universal Unity Maintain field for the resident’s name or email. |
Status | Status | IsClosed and Cancel also indicate whether the request has been closed or cancelled. |
Image | Attachment | Images are transferred as Service Request attachments. Other file types are not supported. |
The Unity Maintain schema does not define universal required values or defaults for these fields. Requirements may depend on the organization’s configuration and the selected Problem.
Unity Maintain also provides customer-configurable fields:
Text1throughText20Num1throughNum5Date1throughDate5
Any use of these fields must be agreed upon during implementation and recorded in the organization’s integration configuration.
Acknowledgment Messages
When a new issue is successfully transmitted to the remote system, SeeClickFix 311 CRM transitions the issue from Open to Acknowledged. Configure the automated acknowledgement message that includes the remote request ID. If no custom message is specified, SeeClickFix 311 CRM uses the default acknowledgement message.
Custom Fields
During service-request submission, SeeClickFix 311 CRM can attach additional custom fields. Custom-field requests are reviewed to confirm that SeeClickFix 311 CRM can satisfy the specified requirements.
Service Request Activity
SeeClickFix 311 CRMx 311 CRM periodically polls Unity Maintain for updated information about remote service requests associated with issues in the Acknowledged state. The integration can observe remote fields and post messages based on the observed values. Only a single activity message is supported.
Service Request Closed
When a remote service request transitions to a completed status, SeeClickFix 311 CRM transitions the issue to Closed and stops synchronizing it. Later changes to the closed remote service request are not reflected in SeeClickFix 311 CRM.
To detect completion, provide the Implementation Manager with the remote status value or values that represent a completed service request.
Once a request transitions to Closed, SeeClickFix 311 CRM stops polling the remote system. Comments added in Unity Maintain after closure are not imported.
The closing transition posts a closing message to the issue. The default message can be customized or specialized by remote status.
Service Request Cancellation
SeeClickFix 311 CRM can be configured to cancel an Acknowledged issue when the remote service request transitions to a cancelled status. The integration transitions the issue back to Open and stops synchronizing it.
The now-open issue can be handled directly in SeeClickFix 311 CRMRM or recategorized, which can trigger another integration according to the new request type configuration.
To detect cancellation, provide the Implementation Manager with the remote status code that represents cancellation.
Once a request transitions back to Open, SeeClickFix 311 CRM stops polling the remote system. Comments added in Unity Maintain after cancellation are not imported.
The cancellation transition posts a cancellation message to the issue. The default message can be customized or specialized by remote status.
Service Request Comment Synchronization
Comments Added Using SeeClickFix 311 CRM
When a public comment is added to a SeeClickFix 311 CRM issue, the comment is visible in SeeClickFix 311 CRM and is submitted to the remote system.
Comments Added Using the Remote System
By default, comments added to the remote service request are ignored by the SeeClickFix 311 CRM integration. To import a remote comment into SeeClickFix 311 CRM, select Make Public in Respond. The control may need to be exposed through Style and included in the Respond profile used by staff.
Related Trimble Documentation
See Trimble Unity Maintain Help Guides for current Admin, Respond, Style, and related product documentation.
Troubleshooting
If the integration stops working after a Unity Maintain upgrade or authentication change:
Verify the Unity Maintain endpoint, API-user name, and configured credential.
Verify that API Only is enabled on the Unity Maintain employee record and that the required API credentials and licenses remain assigned.
Verify that the required Problems, fields, and status values have not changed.
Contact CivicPlus Technical Support if the integration continues to fail.