SeeClickFix Connect for Cityworks: Technical Requirements & Configuration – SeeClickFix

Outlined below is the information that SeeClickFix requires to configure integration between Cityworks and SeeClickFix.

Important Note

All the sensitive information requested in this document should be entered directly into the system. Please do not send SeeClickFix credentials for any remote system. Please direct any questions about this document to your Implementation Manager or Support.

Terminology

SeeClickFix 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 system.	Client application
Remote system or integrated system	The Cityworks integrated system.	Cityworks
Issue or local service request	The issue information is available via SeeClickFix.	N/A
Remote service request	The service request information available via Cityworks Server.	Service Request
Issue id	The primary key for the issue in SeeClickFix.	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.	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 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 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 staff member. This is to make sure that your remote system credentials are secure. The user credentials provided to SeeClickFix must have permission to create and update service requests. To enter your credentials into SeeClickFix directly, follow these steps:

If you are providing the Test Endpoint credentials to SeeClickFix, log in to the SeeClickFix Integrations Environment. If you are providing the Production Endpoint credentials to SeeClickFix, login to the SeeClickFix Production environment:
1. Integrations: https://crm-int.seeclickfix.com
2. Production: https://crm.seeclickfix.com
Navigate to the Profile Icon > 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 Integrations setting page, please reach out to Cityworks Support with that error message to receive additional assistance.

Firewalls

Many partners have network security equipment (firewalls) installed to protect their systems. These systems must be configured to permit SeeClickFix systems to establish connections to the remote system. Please ensure that SeeClickFix IP addresses have been whitelisted to pass through any firewalls:

SeeClickFix Integrations Environment IP: 66.228.40.16
SeeClickFix Production Environment IP: 69.164.215.225

Integration User

During the normal operations of an integration, SeeClickFix 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 Spatial Reference Identifier (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 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 integration settings to 3857. If a customer is upgrading their Cityworks, it is necessary to make sure this field is correctly set in SeeClickFix.

Address Validation

By default, SeeClickFix will pass latitude, longitude, and address fields during service request creation. SeeClickFix 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 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 via the Cityworks Web Services problems method (e.g ForPublicWebsite = TRUE).

Secondary Questions

SeeClickFix 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 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 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 enforces the required attribute on questions and ensures the response contains text other than whitespace (e.g. spaces and tabs).

Question Order

SeeClickFix will present questions in the order specified by the QuestionSequence property.

Service Request Synchronization

The primary function of a SeeClickFix 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, 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 SCF 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”
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 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 can attach additional custom fields. Custom field requests will be reviewed to confirm that SeeClickFix is able to satisfy the specified requirements.

Service Request Activity

Periodically, SeeClickFix 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 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 on 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 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 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 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 will transition the issue to Open and cease synchronization of the issue. The now-open issue may be handled directly within SeeClickFix 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 cancelation.

Once a service request has transitioned back to Open, SeeClickFix 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 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 via SeeClickFix

When a comment is made to an issue via SeeClickFix, the comment will be visible via SeeClickFix and will be submitted to the remote system.

Comments Added via Remote System

By default, comments made on the remote service request via the remote system are ignored by the SeeClickFix 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.

Search