Welcome to the OpenCities help centre. Search for what you're after, or browse the categories.
Can't find what you're looking for? Submit a support ticket and we'll be in touch.

Follow

EngagementHQ x OpenCities Connector Setup Guide

avatar of OpenCities Product Team

OpenCities Product Team

Last updated

This task is for users with the OC Site Manager, OC System Administrator, and OC Developer roles.

You can start the setup once you have installed the EngagementHQ connector module. This article will take you through how to:

Please consult our FAQs about the connector if you have any questions.

Configure the Connection in Your Sentiment & Feedback Environment

To configure the connection, you will need the Site Administrator role in Sentiment & Feedback and the OC Developer role in CMS OE (OpenCities).

To configure the connection, you'll need access to both platform admins; we recommend opening both in separate tabs before you start.

  1. In your Sentiment & Feedback admin, go to Marketplace and select OpenCities.
    The marketplace screen in EngagementHQ
  2. Select Edit Settings in the top-right of the page; then, you must populate the App ID, API key, Admin URL, and Folder path fields with information from your CMS admin.
    The OpenCities connector settings in EngagementHQ
  3. Switch over to your CMS admin and go to More > API Management.
  4. Copy and paste the App ID and API Key into the corresponding fields in Sentiment & Feedback.
    create key.png
  5. Copy and paste your admin URL (the URL you use to log into your CMS admin site) into the corresponding field in Sentiment & Feedback.
    admin domain
  6. Select your parent folder in the site tree to find the Folder path. This folder is automatically created when installing the EngagementHQ Connector. Select the folder path below the title to expand the internal link, and then copy and paste it into the corresponding field in your Sentiment & Feedback admin.
    EngagementHQ folder file path
  7. Once all the fields in your Sentiment & Feedback settings are filled, select Save.

Now that the Connector has been enabled in your engagement admin, publicly visible projects will sync and display on your CMS OE website over 24 hours.

How to Use the Connector

Once the connector has been enabled, the OC EngagementHQ Project content type will be available in your CMS. A parent folder for engagement projects will also be created in your site tree. All projects synced over will be produced as OC EngagementHQ Project child pages under the parent folder.

You can now configure how your projects will display on your CMS OE website and add metadata to make the project easier to find, including:

  • Adding a project image to improve how they display on your homepage
  • Adding keywords to improve search results
  • Adding content labels to show projects in dynamic content lists
  • Adding locations to show projects on maps, including My Area

If your project has a scheduled archive date, this date will sync as the consultation closing date for your website. If your project has no scheduled archive date, the Ongoing consultation checkbox will be ticked.

We recommend adding a metadata description to each project in Sentiment & Feedback, which will be used as the description on your CMS OE site. To do this, go to the project in your engagement environment and go to Settings > Advanced > Set HTML Metadata, and type the description in the Enter meta description text field. Save when you're done.

Display 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.

  1. Go to More > Site Management > your site > Settings > Site Search.
  2. Under Select which content types are included in site search, check the box for OC EngagementHQ Project.
  3. If you have previously checked Yes to Include same content types in 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 predictive search.
  4. 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 Projects on Your Homepage

You can configure projects on your homepage, including how they are filtered and sorted and displayed.

  1. Go to More > Site Management > your site > Settings > Community Engagement, and expand the Manage the content that appears on site listing accordion menu.
  2. 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
  3. You can also use the Homepage listing call to action link URL field to add a call-to-action button linking back to your Sentiment & Feedback site from your homepage listing.
  4. Select Save Settings and Save.

Community engagement site management

You can pin or hide individual project pages to your homepage using the drop-down selector on an OC EngagementHQ Project page.
The pin or hide projects setting

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

  1. In your site tree, right-click on your homepage tab folder and create a new OC Tab Widget page.
  2. Add a Page name and Tab Label, then select OC Homepage Consultation Listing from the Template Name drop-down menu.
    EngagementHQ tab for homepage
  3. 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.

  1. Go to More > Themes Management > your theme > Layout.
  2. Select Add row, then drag and drop the Consultation list into your new row.
  3. 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.
  4. Select Apply, then Preview your theme.
    Consultation row for homepage
  5. 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 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.

  1. Go to More > Maps > Layers.
  2. Select Create layer, or select an existing layer to edit it.
  3. Fill out all the fields for your layer, ensuring you specify OC EngagementHQ Project under Content types to include.
    EngagementHQ pages on a map layer
  4. Save your layer, then go to Maps.
  5. Select your map from the list and go to the Layers tab.
  6. Select Add shared layer, locate your EngagementHQ layer in the list, and select Add to map.
  7. Preview and Save your map.

OC EngagementHQ Project pages must have the Latitude Longitude field populated in CMS OE before they will display on a map.

FAQs About the Connector

  • If I change my project, will the updates flow through to the CMS?
    Yes, any updates to projects in Sentiment & Feedback will be visible in the CMS. You must wait for the project to sync for the changes to be visible on the website. Content will only synchronize in one direction, from Sentiment & Feedback to CMS OE.
  • If I make updates in the CMS, will that change anything in Sentiment & Feedback?
    No, any updates made in the CMS will not change projects in Sentiment & Feedback. Content will only synchronize in one direction, so you need to adjust any content or settings in your engagement site.
  • What updates can I make to the project in the CMS?
    When projects sync across, they will be created as OC EngagementHQ Project pages. To keep content consistent across both platforms, some fields will be locked in the CMS; 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 Sentiment & Feedback; you must add it manually to the OC EngagementHQ Project page.
    • Project URL: Locked
    • Latitude Longitude: Unlocked
      • Note: This content will not sync from Sentiment & Feedback; you must 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 the CMS?
    This is how those fields are filled:
    1. When a published project, with no scheduled archive date, syncs to the CMS, the Ongoing consultation box will be checked, and the default closing date will auto-fill. Because the Project Dates fields are locked, you cannot change this in the CMS.
    2. If an admin then schedules an archive date for the project in Sentiment & Feedback, on the next sync, that date will replace the default closing date, and the Ongoing consultation box will uncheck.
    3. However, if an admin archives a project immediately in Sentiment & Feedback, the next sync will not change the CMS webpage because archived content does not sync across. 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 project, it will sync as the consultation closing date on the corresponding OC EngagementHQ Project page. However, because archived pages do not sync from Sentiment & Feedback, if you archive a project immediately, that change will not sync to the page in the CMS. You must Archive, Roll Back, or deactivate the webpage 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 engagement environment so that they sync across to the CMS.
  • 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 the CMS admin. The only way to force a sync is to go to the connection settings in your Sentiment & Feedback 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 CMS OE website.
  • Can any user configure the connector?
    No, only users with the OC Site Manager, OC System Administrator, or OC Developer roles can configure the connector. Users with access to the Marketplace pages on Sentiment & Feedback include the Site Administrator or Hub Administrator roles.
  • Will all projects be displayed in the CMS, 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 paneled 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 projects be indexed on search engines for both sites?
    By default, each project page in the CMS will be hidden from external search engines so the Sentiment & Feedback search engine results take priority.
  • If you move the folder in the site tree, does it stop the connector from working?
    If you move the folder in the CMS site tree, 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 Sentiment & Feedback with the new folder name. Once you have updated your configuration and synced pages to the new folder, you can copy any manually entered details over from the old pages and delete or archive the old directory.
  • If you rename the folder in the site tree, will the connector stop working?
    If you rename the folder in the CMS site tree, the connector will stop working. If you must rename your folder, please create a new folder and update your connector configuration details in Sentiment & Feedback with the new folder name. Once you have updated the configuration and synced pages 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 engagement site to multiple CMS OE sites?
    No, you cannot connect Sentiment & Feedback to multiple CMS OE sites. Only one Sentiment & Feedback site can be connected to one CMS OE site.
  • What's the number next to the Page name?
    This is a page's unique identifier to ensure it can be created in the CMS without any errors. This number will not be displayed on the live site.
  • How is the Project Description populated in the CMS?
    The Project Description field in CMS OE 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 project description in Sentiment & Feedback.
    • The meta description can be found in the project Settings > Advanced > Set HTML metadata
  • What if my organization uses the CMS Community Engagement module as well?
    If your city or council uses the 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 to display both OC Consultation and OC EngagementHQ Project pages in your listings.
Was this article helpful?
0 out of 1 found this helpful