Improve project discoverability, tap into relevant feedback, and cross-promote at scale by connecting EngagementHQ to your OpenCities website.
With the EngagementHQ x OpenCities connector, you can:
Link to EngagementHQ projects on your OpenCities homepage
Automatically surface EngagementHQ projects in OpenCities search results
Surface location-based projects in My Area
Highlight projects in navigation using Top Tasks
OpenCities users who hold the Site Manager or System Administrator role and EngagementHQ users who hold the Site Administrator role can self-serve and configure the integration without support
Add to dynamic content lists using OpenCities content labels to enable project suggestions to display while residents browse
Manual sync on save
Project visibility respected in the sync (public, private, panelled)
By linking your OpenCities account, you permit EngagementHQ to surface publicly visible projects within OpenCities search results. This article will cover:
The ability to manage EngagementHQ projects in the OpenCities CMS is available to OpenCities customers who hold the OC Site Manager, OC System Administrator, and OC Developer roles by following the instructions below.
Configure the connection in your EngagementHQ environment
To configure the connection, you'll need access to your EngagementHQ and OpenCities admin; we recommend opening both in separate tabs before you start.
In your EngagementHQ admin, go to Marketplace and select OpenCities.
Select Edit Settings in the top right of the page; then, you'll need to populate the App ID, API key, Admin URL, and Folder path fields with information from your OpenCities admin.
Switch over to your OpenCities admin and go to More > API Management.
Copy and paste the App ID and API Key into the corresponding fields in EngagementHQ.
Copy and paste your admin URL (the URL you use to log into your OpenCities admin site) into the corresponding field in EngagementHQ.
Select your EngagementHQ parent folder in the site tree to find the Folder path. Select the folder path below the title to expand the internal link, and then copy and paste it into the corresponding field in your EngagementHQ admin.
Once all the fields in your EngagementHQ settings are filled, select Save.
Now that the Connector has been enabled in your EngagementHQ admin, publicly visible projects will start syncing and display on your OpenCities site over the next 24 hours.
How to use the connector
Once the EngagementHQ x OpenCities Connector has been enabled, the OC EngagementHQ Project content type will be available on your OpenCities site.
A parent folder for EngagementHQ projects will also be created in your site tree. All projects synced over from EngagementHQ will be produced as OC EngagementHQ Project child pages under the parent folder.
You can now configure how your projects will display on your OpenCities site and add metadata to make the project easier to find, including:
Adding a project image to improve how they display on the homepage
Adding keywords to improve search results
Adding content labels to show projects in dynamic content lists
If your project has a scheduled archive date, this date will sync as the consultation closing date in OpenCities. If your project has no scheduled archive date, the Ongoing consultation checkbox will be ticked in OpenCities.
We recommend adding a metadata description to each project in EngagementHQ, so this will be used as the description on your OpenCities site. To do this, go to the project in your EngagementHQ admin, go to Settings > Advanced > Set HTML Metadata, and type the description in the Enter meta description text field. Save when you're done.
Display EngagementHQ projects in site search
To allow residents to find projects using your internal site search, you'll need to enable the content type in the Site Search Settings.
Go to More > Site Management > your site > Settings > Site Search.
Under Select which content types are included in site search, check the box for OC EngagementHQ Project.
If you have previously checked Yes to Include the same content types in the predictive search, then your OC EngagementHQ Project pages will automatically surface in your predictive search. If not, ensure the content type is checked under Select which content types are included in the predictive search.
Select Save Settings and Save.
By default, OC EngagementHQ Project pages will be hidden from external search engines so they won't index duplicate results.
Display EngagementHQ projects on your homepage
You can configure projects on your homepage, including how they are filtered and sorted and display.
Go to More > Site Management > your site > Settings > Community Engagement, and expand the Manage the content that appears on the site listing accordion menu.
Under Select content types, ensure the OC EngagementHQ Project content type is selected, and choose how your projects are sorted and ordered on the homepage
You can also use the Homepage listing call-to-action link URL field to add a call-to-action button linking back to your EngagementHQ site to your homepage listing.
Select Save Settings and Save.
You can also pin or hide each project page on your homepage.
Now, you need to configure your homepage to display your projects. There are two ways you can do this.
List projects in a homepage tab
In your site tree, right-click on your homepage tab folder and create a new OC Tab Widget page.
Add a Page name and Tab Label, then select OC Homepage Consultation Listing from the Template Name dropdown menu.
You can Preview what will appear on the listing, but you'll need to Publish the page to see it live on your homepage.
List projects in a homepage row
To list projects in a homepage row, you'll need to edit your theme; for this, you'll need the OC Site Designer role.
Go to More > Themes Management > your theme > Layout.
Select Add row, then drag and drop the Consultation list into your new row.
Select the Maximum number of items to display on your homepage list, and choose if you want to show them in Rows or a Carousel.
Select Apply, then Preview your theme.
Publish your theme when you're ready. Remember, if you Publish a theme that's in use on your site, your changes will be live immediately.
Display EngagementHQ projects on maps
You can configure maps to display OC EngagementHQ Project pages, including listing them on your My Area map so residents can check out what consultations are around them.
To do this, you'll need to edit maps and layers, for which you'll need the OC Map Manager role.
Go to More > Maps > Layers.
Select Create layer, or select an existing layer to edit it.
Fill out all the fields for your layer, ensuring you specify OC EngagementHQ Project under Content types to include.
Save your layer, then go to Maps.
Select your map from the list and go to the Layers tab.
Select Add a shared layer, locate your EngagementHQ layer in the list and select Add to map.
Preview and Save your map.
Remember that OC EngagementHQ Project pages must have the Latitude Longitude field populated in OpenCities before they display on a map.
FAQs
If I change my EngagementHQ project, will the updates flow through to OpenCities?
Yes, any updates to EngagementHQ projects will be visible in OpenCities. You will have to wait for the project to sync for the changes to be visible on OpenCities. Content will only synchronize in one direction, from EngagementHQ to OpenCities.
If I make updates in OpenCities, will that change anything in EngagementHQ?
No, any updates to OpenCities will not change EngagementHQ projects. Content will only synchronize in one direction, from EngagementHQ to OpenCities. Remember that this means content needs to be adjusted in EngagementHQ.
What updates can I make to the project in OpenCities?
When projects sync across from EngagementHQ, they will be created as OC EngagementHQ Project pages. In order to keep content consistent across both platforms, some fields will be locked in OpenCities; here is what you can and cannot edit:
Page name: unlocked
Project Title: locked
Project Description: locked
Project Image: unlocked
Note: this content will not sync from EngagementHQ; you will need to add it manually.
Project URL: locked
Latitude Longitude: unlocked
Note: this content will not sync from EngagementHQ; you will need to add it manually for the project to display on maps.Choose how this content will display on homepage listings: unlocked
Additional Information section: unlocked
Project Dates: locked
What content syncs to the Ongoing consultation and consultation close fields in OpenCities?
This is how those fields are filled:
When a published EngagementHQ project, with no scheduled archive date, syncs to OpenCities, the Ongoing consultation box is checked and a default closing date will auto-fill. Because the Project Dates fields are locked, you cannot change this in OpenCities.
If an admin then schedules an archive date for the project in EngagementHQ, on the next sync, that date will replace the default closing date, and the Ongoing consultation box will uncheck.
However, if an admin archives a project immediately in EngagementHQ, the next sync will not change the OpenCities page because archived content does not sync from EngagementHQ. The user must manually Archive or Roll Back the page to remove it from the site.
How do I archive projects?
When you schedule an archive date on your EngagementHQ project, it will sync as the consultation closing date on the corresponding OC EngagementHQ Project page. However, because archived pages do not sync from EngagementHQ, if you choose to archive a project immediately, that change will not sync to the page in OpenCities. You must Archive, Roll Back, or deactivate the page in OpenCities to remove it from your site.
Why are my projects not appearing on my homepage?
Projects will only display on the homepage if they are ongoing or have a closing date in the future. Please change these dates in your EngagementHQ environment so that they sync across to OpenCities. You can schedule an archive date to fill the consultation closing date in OpenCities, or leave it published and open to check the Ongoing consultation box.
How frequently does the sync run?
The sync is set to run every 4 hours.
Can I manually sync projects?
You cannot manually sync projects from OpenCities. The only way to force a sync is to go to the connection settings in your EngagementHQ environment and select Save. This will manually start an immediate sync. Please note that if there are many updates to sync across, it could take some time before they are all visible on your OpenCities site.
Can any user configure the connector?
No, only users with the OC Site Manager, OC System Administrator, or OC Developer roles in OpenCities. Users with access to the Marketplace pages on EngagementHQ include the Site Administrator or Hub Administrator roles.
Will all EngagementHQ projects be displayed in OpenCities, including Protected, Hidden, Static, Published, and Archived?
Project visibility will be respected in the sync (public, private, paneled);
Content that will be synced:
Published project pages with public or panelled visibility
Content that will not be synced:
Project pages in draft
Archived project pages
Project pages with private visibility or password protection
Static pages, such as privacy policies, terms and conditions, or hub pages
Will EngagementHQ projects be indexed on search engines for OpenCities sites and EngagementHQ sites?
By default, each project page in OpenCities will be hidden from external search engines, so they don't cannibalize EngagementHQ search engine results.
If you move the folder in OpenCities, does it stop the connector from working?
If you move the folder in OpenCities, the connector will stop working. If you must use a new folder, please create it in its correct location and update your connector configuration details in EngagementHQ with the new folder name. Once you have updated your configuration and pages have been synced to the new folder, you can copy any manually entered details over from the older pages and delete or archive the old directory.
If you rename the folder in OpenCities, will the connector stop working?
If you rename the folder in OpenCities, the connector will stop working. If you must rename your folder, please create a new folder and update your connector configuration details in EngagementHQ with the new folder name. Once you have updated the configuration and pages have been synced to the new folder, you can copy any manually entered details over from the old pages and delete or archive the old directory.
Does the participation type need to be set to "Anyone"?
No, participation type impacts which users can contribute to tools within a project. It does not impact whether or not a project will be synced. Once a project is published and public, it will be synced and displayed.
Can I connect my EngagementHQ site to multiple OpenCities sites?
No, you cannot connect EngagementHQ to multiple OpenCities sites. Only one EngagementHQ site can be connected to one OpenCities site.
What's the number next to the Page name?
This is a page's unique identifier to ensure it can be created in OpenCities without any errors. This number will not display in OpenCities.
How is the Project Description populated in OpenCities?
The Project Description field in OpenCities can be populated either by the project meta description or, if the meta description field is left blank, default to the first 300 characters of the EngagementHQ project summary. The meta description can be found and edited in the project Settings > Advanced > Set HTML metadata.
What if my organization uses the OpenCities Community Engagement module as well?
If your city or council uses the OpenCities Community Engagement module, your Community Engagement Site Management settings will also display options for the content types in that module. You can also choose whether you want to display both OC Consultation and OC EngagementHQ Project pages in your listings.
Helpful Resources