Important Notes
The license for the third-party software's API utilized for this integration may require additional cost from that vendor. Please confirm your organization's API access and license with your third-party vendor.
Cityworks has released Cityworks 23, which is a significant upgrade. The new version requires a change in authentication. The SeeClickFix 311 CRM solution is prepared for the upgrade and can work with customers to update the integration in sync with the update the organization does with their Cityworks solution. Any organization that is updating its Cityworks system should submit a Support ticket so that SeeClickFix 311 CRM can update the integration appropriately.
Requirements
Versions: 2013 (JSON API), 2014, 2015, 15.0-15.8, 23+
On-premise or online
Service Requests (SR) and/or Work Orders (WO)
Citizen Engagement API license and/or Work Order Basic API
Features
Syncing Categories
The Integration can query Cityworks for a list of public Service Requests (SR) or Work Order (WO) "Templates", to be used as request categories on SeeClickFix 311 CRM report forms.
Request categories are grouped into one or more customer-defined "agencies", each with a geographical service area. These geographies are configured using polygon shapefiles uploaded to SeeClickFix 311 CRM.
There is no limit to the number of categories that can be synced with Cityworks.
This query runs on a schedule but can also be triggered on demand using the SeeClickFix 311 CRM internal system.
Syncing Questions & Answers (Service Requests Only)
For each request category synced with a Cityworks SR template, the integration will query Cityworks for a list of Questions and Answers.
The Cityworks integration views questions synced from Cityworks as Public on SeeClickFix 311 CRM unless the question text contains "email", "e-mail", or "phone". If any of those words are used in the question, then the question will be marked as Private. If a secondary question should be kept Private within SeeClickFix 311 CRM, then the automatic sync for secondary questions should be disabled. This must be completed by a SeeClickFix 311 CRM Administrator.
Questions imported using the automatic sync process are always marked as "required" within SeeClickFix 311 CRM.
This query runs on a schedule, but can also be triggered on demand using the SeeClickFix 311 CRM internal system.
Address Lookup
Prior to creating a Service Request in Cityworks, the Integration can query a customer-provided ArcGIS server for an address, based on the X/Y map coordinates of the request (reverse geocode).
Submitting Requests
As requests are created on SeeClickFix 311 CRM, the Integration submits them to Cityworks individually (on-the-fly), as a new Service Request or Work Order.
If an issue includes an image, the Integration submits it to Cityworks as a Service Request/Work Order Attachment.
Importing Requests (Service Requests Only)
The Integration can periodically query Cityworks for new SR originating in Cityworks directly. This allows SeeClickFix 311 CRM applications (web portal and mobile apps) to display all Cityworks SRs, not just those originating SeeClickFix 311 CRM.
The importer feature requires a standard polygon without cutouts to be used for the geography of the agency. For example, a geography with state highways cut out of polygon will cause errors in the importer.
Submitting Comments
As public comments are added on SeeClickFix 311 CRM, the Integration submits them to Cityworks individually (on the fly), as Service Requests/Work Order comments.
If a comment includes an image, the Integration submits it to Cityworks as an SR/WO Attachment.
Importing Comments
The Integration will periodically query Cityworks for comments added to the SR/WO and will import those intended for public consumption.
NB: this "Public" indicator is currently implemented using a comment prefix "To SCF:", pending the addition of a proper checkbox field for this purpose.
Checking for Updates
The Integration will periodically query Cityworks for changes to the SR/WO, in order to take the following actions:
The Integration will close the issue if the Cityworks SR/WO has been closed.
Importing Images (from Cityworks)
SeeClickFix 311 CRM can import images intended for public consumption attached to the SR/WO in Cityworks.
If the attachment includes a comment with the prefix "To SCF:", the content of the comment, along with the image, will be imported to SeeClickFix 311 CRM and posted as a public comment on the request.
Technical Requirements & Configuration
Outlined below is the information that SeeClickFix 311 CRM requires to configure integration between Cityworks and SeeClickFix 311 CRM.
Important Notes
All the sensitive information requested in this document should be entered directly into the system. Please do not send SeeClickFix 311 CRM credentials for any remote system. Please direct any questions about this document to your Implementation Manager or Support.
Terminology
SeeClickFix 311 CRM systems integrate with a wide variety of external service requests and work order systems. The following table describes the terminology used in this document and the associated terms in the remote system.
Document Term | Description | Cityworks Term |
|---|---|---|
Local system | The SeeClickFix 311 CRM system. | Client application |
Remote system or integrated system | The Cityworks integrated system. | Cityworks |
Issue or local service request | The issue information is available from SeeClickFix 311 CRM. | N/A |
Remote service request | The service request information is available on the Cityworks Server. | 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 incident in Cityworks. | RequestId field of Service Request |
Service request type or request type | The type of service 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 incident in Cityworks Server. | Status field of Service Request |
Secondary questions | Additional questions associated with a request type. | See secondary question section |
Service Endpoints and Network Access
A service endpoint is identified by a URL and represents a connection point where SeeClickFix 311 CRM accesses your systems. We strongly recommend that you make available a test endpoint that is not associated with your production system. This allows the integration to be thoroughly tested before any changes are made to your production system.
Item | Description | Required? |
|---|---|---|
Test Endpoint | The URL specified http://localhost/Cityworks/Services/AMS for your test system (the Services/AMS endpoint) | Yes |
Test User | The user name for authenticating to the test endpoint and UI access. | Yes |
Test Password | The password for authenticating to the test endpoint and UI access. Enter directly into the Integrations tab within the SCF-INT. | Yes |
Production Endpoint | The URL specified http://localhost/Cityworks/Services/AMS for your Production system (the Services/AMS endpoint) | Yes |
Production User | The user name for authenticating to the production endpoint. | Yes |
Production Password | The password for authenticating to the production endpoint. Enter directly into the Integrations tab within the SeeClickFix 311 CRM internal system. | Yes |
User Names and Passwords
The remote system credentials are entered into the system directly and should not be sent to any SeeClickFix 311 CRM staff member. This is to make sure that your remote system credentials are secure. The user credentials provided to SeeClickFix 311 CRM must have permission to create and update service requests. To enter your credentials into SeeClickFix 311 CRM directly, follow these steps:
If you are providing the Test Endpoint credentials to SeeClickFix 311 CRM, log in to the SeeClickFix 311 CRM Integrations Environment. If you are providing the Production Endpoint credentials to SeeClickFix 311 CRM, log in to the SeeClickFix 311 CRM Production environment:
Integrations: https://crm-int.seeclickfix.com
Production: https://crm.seeclickfix.com
Navigate to the Profile Icon and select Manage Organization
Along the left-hand side, click Integrations
Enter your credentials into the available fields
Using Windows Authentication for Cityworks (Optional)
In the case that your organization uses Windows Authentication for your Cityworks instance or you wish to set up Windows Authentication for Cityworks, please use the Cityworks provided documentation.
Once Windows Authentication is set up, you will use the following username format to authenticate: domain/username.
If you receive a password after setting up Windows Authentication and attempting to authenticate through the SeeClickFix 311 CRM Integrations setting page, please reach out to Cityworks Support with that error message to receive additional assistance.
Firewalls
Many customers have network security equipment installed (firewalls) to protect their systems. In this case, your IT staff or vendor will need to ensure that SeeClickFix 311 CRM systems are permitted to establish connections to your CentralSquare EAM systems by allowlisting the IPs.
Integration User
During the normal operations of an integration, SeeClickFix 311 CRM will add a variety of system messages to the local service request, including acknowledgment messages and closing messages. The Integration Bot User Name is the name of the user that will appear on these system messages. The default Integration Bot User Name will be your organization's title (example: City of New Haven). However, this can be adjusted at any time by adjusting the Display Name of this user within the Member list.
GIS Information
SRID Projection
For Cityworks versions lower than 15.8, please provide the SRID used by the remote system to your Implementation Manager. If you are unsure of your specific SRID, you can search for SRID values. SeeClickFix 311 CRM will translate all latitude and longitude coordinates to this SRID when sending data to the remote system.
For Cityworks 15.8+, the SRID must be set within the SeeClickFix 311 CRM integration settings to 3857. If a customer is upgrading their Cityworks, it is necessary to make sure this field is correctly set in SeeClickFix 311 CRM.
Address Validation
By default, SeeClickFix 311 CRM will pass latitude, longitude, and address fields during service request creation. SeeClickFix 311 CRM can additionally validate this information against an ArcGIS server associated with the remote system and report the ArcGIS result. If you have your own ArcGIS Server, please provide it to your Implementation Manager.
Service Request Types
Remote Request Types
SeeClickFix 311 CRM uses Cityworks Web Services to define the service requests and any secondary questions offered during issue reporting. Service requests must be defined on the remote system such that they are visible using the Cityworks Web Services problems method (ForPublicWebsite = TRUE).
Secondary Questions
SeeClickFix 311 CRM reporting systems always ask for a summary, description, and an optional image when collecting service request details. In addition, secondary questions can be configured on a per-request-category basis to prompt the reporter for additional information.
Remote Secondary Questions
SeeClickFix 311 CRM uses Cityworks Web Services to define the secondary questions presented during reporting. The following data types for secondary questions included in the Cityworks QA response are supported: FREETEXT, THISTEXT, NO, YES, DATE. Branching questions are not supported at this time.
Email Attributes
SeeClickFix 311 CRM retains the additional form field descriptions and responses in the local service request and includes that data in the public view of the issue. If the question field of a ProblemQuestionBase object contains the text "email," the question and answer will not be displayed publicly. This guards against private email addresses being revealed unintentionally.
Required Attributes
SeeClickFix 311 CRM enforces the required attribute on questions and ensures the response contains text other than whitespace (such as spaces and tabs).
Question Order
SeeClickFix 311 CRM will present questions in the order specified by the QuestionSequence property.
Service Request Synchronization
The primary function of a SeeClickFix 311 CRM integration is to keep the local service request synchronized with the remote service request. For example, when a service request associated with the remote system is created on SeeClickFix 311 CRM, the integration creates a matching remote service request. When the remote service request is marked as complete in the remote system, the integration updates the local service request to reflect that change. The following table shows the relationship between the local service request status and the remote service request status using the generic terms "open" and "closed" for the remote status.
Local Status | Remote Status | Notes |
|---|---|---|
Open | N/A | The service request has been reported to SeeClickFix 311 CRM but has not yet been accepted by the remote system. |
Acknowledged | Open | The service request has been accepted by the remote system. |
Closed | Closed | The service request has been closed. |
Archived | Closed | The service request has been closed for more than two weeks. |
Service Request Creation
Issue Field Mapping
The following table shows the mapping of local service request information to the Cityworks remote service request.
Local Field | Remote Field | Notes |
|---|---|---|
n/a | CallerFirstName | "SeeClickFix 311 CRM" |
reporter_display | CallerLastName | The reporter's name. |
reporter_email | CallerEmail | The reporter's email. |
summary and description | Details | The two fields are joined with a separating new line. |
lat | Y | The reported latitude is projected using the remote SRID. |
lng | X | The reported longitude is projected using the remote SRID. |
address | Address | The reported address or the ArcGIS verified address. |
image_url | no default | The image URL can be mapped to a custom property such as Text1, Text2, … |
Acknowledgment Messages
When a new issue is successfully transmitted to the remote system, SeeClickFix 311 CRM will transition the issue from Open to Acknowledged. Specify the text of the automated Work Order ID acknowledging the message, which will be added as a message to the issue. Default Acknowledgement Message: If no custom acknowledgment message is specified, the default message is used.
Custom Fields
During service request submission, SeeClickFix 311 CRM can attach additional custom fields. Custom field requests will be reviewed to confirm that SeeClickFix 311 CRM is able to satisfy the specified requirements.
Service Request Activity
Periodically, SeeClickFix 311 CRM polls the remote system to retrieve updated information regarding the remote service requests associated with any issues that are in the Acknowledged state. The integration can observe fields in the remote service request and post messages based on the observed values. Currently, only a single activity message is supported.
Service Request Closed
When the status of the remote service request transitions to close, SeeClickFix 311 CRM will transition the issue to Closed and cease synchronization of the issue. Changes made to a closed service request on the remote system will never be reflected in the issue.
Acknowledged to Closed: In order for the integration to detect when the remote service request has been completed, indicate to your implementation manager the remote Status value(s) that represent a completed service request.
Once a service request has transitioned to Closed, SeeClickFix 311 CRM will cease polling the remote system for that service request. As such, no comments will be pulled from the remote system once the service request is closed.
Closing Messages: The transition to Closed causes SeeClickFix 311 CRM to post a closing message to the issue. The default closing message can be customized, or the closing message can be specialized based on the Status. Specify these to your Implementation Manager.
Service Request Cancellation
SeeClickFix 311 CRM can be configured to cancel an issue that is in the Acknowledged state when the status of the remote service request indicates that it has been canceled. When the status of the remote service request transitions to a canceled state, SeeClickFix 311 CRM will transition the issue to Open and cease synchronization of the issue. The now-open issue may be handled directly within SeeClickFix 311 CRM or recategorized, potentially triggering another integration based on the configuration of the new request type.
Acknowledged to Open: In order for the integration to detect when the remote service request has been canceled, please indicate to your implementation manager the status code that references cancellation.
Once a service request has transitioned back to Open, SeeClickFix 311 CRM will cease polling the remote system for that service request. As such, no comments will be pulled from the remote system once the service request is canceled.
Cancel Messages: The transition to Open causes SeeClickFix 311 CRM to post a canceled message to the issue. The default cancel message can be customized, or the cancel message can be specialized based on the remote Status. Specify these to your Implementation Manager.
Service Request Comment Synchronization
Comments Added Using SeeClickFix 311 CRM
When a comment is made to an issue using /, the comment will be visible in SeeClickFix 311 CRM and will be submitted to the remote system.
Comments Added Using Remote System
By default, comments made on the remote service request using the remote system are ignored by the SeeClickFix 311 CRM integration. You can cause a comment to be pulled from the remote system and added to the local service request by entering a comment starting with "To SCF:" on the remote system.