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.