The NC State Knowledge plugin helps you COPE

The NC State Knowledge plugin is now available for campus websites to install and activate via Cthulhu. Instructions on installation is available in the usage documentation.

Note: This plugin is stable and ready for use, but still under active development. In particular, the user interface in WordPress may change as we refine the plugin.

As I write this, NC State is attempting to reopen and reactivate campus in the midst of a global pandemic. The challenges of safely providing (at least partially) in-person instruction and (something resembling) a traditional on-campus student experience are enormous. I’m grateful that most of these decisions are above my pay grade.

But if it’s going to happen safely, clear and consistent communication is essential. Among other things, that means:

  • Every campus website with information about COVID-19 safety protocols and reopening guidelines needs to have accurate and consistent information.
  • When something changes, that information needs to be updated quickly.

This is especially challenging on a campus as big as ours, and with a web landscape as decentralized as ours. While it certainly makes sense to have a single COVID-19/reopening website that compiles everything the campus community needs to know, it also makes sense for some or all of that information to be presented in other contexts and on other websites.

For instance, certain information about campus operations is relevant across many campus units, like how to get a face covering or what to do if you test positive for COVID-19. That information definitely belongs on the central COVID-19 website for campus, but it also makes sense on college websites, departmental intranet websites, websites for student-facing services, and more. And when something changes based on public health recommendations, it’s important that those updates happen across all of these websites immediately.

University leadership and staff in University Communications, Emergency Management & Mission Continuity, OIT, and a number of other campus units have been working over the last few weeks to navigate this challenge (along with a lot of other challenges). For our part, OIT Design & Web Services has been working with the ServiceNow team to build the NC State Knowledge plugin for WordPress. Any COVID-19 information managed centrally in ServiceNow can now be republished to your WordPress website.

This was a big project dropped on us with almost no notice or time to plan. Before I get into the details of how it works, I want to thank my team. Everyone stepped up in a big way, by contributing, testing, writing documentation, and picking up the slack while others were abruptly moved to working on this. Not sure if you all know this, but there are some pretty special people working on the Design & Web Services Team.

An extra-special thank you also goes to Adam Bernot from DASA Tech, who isn’t even part of this team but managed to get roped into contributing code. He’s a good one too.

Create Once, Publish Everywhere

We’re tackling the problem with publishing principles called COPE: Create Once, Publish Everywhere. The COPE philosophy (at least as articulated this way) comes from the team behind National Public Radio’s web presence. A news story is written once and distributed across all of NPR’s programs and member stations.

The way we’re approaching COVID-19 knowledge articles isn’t necessarily the purest form of COPE. For instance, some presentational markup gets added when you create an article in ServiceNow, and that markup does get sent to WordPress. But it’s definitely in the spirit of COPE:

  • Information is modular
  • Information is portable
  • A single “source of truth” knowledge management system manages creation and editing of content

The COPE philosophy also sits behind our Xanadu calendar plugin. For different types of information—calendar events or critical public health information or something else—campus users should use the tool that’s best for managing that information. Rather than trying to find a way to make WordPress do something it shouldn’t do, use the right tool for the job and then let us figure out a way to feed data from that tool into your website.

Knowledge is half the battle

ServiceNow is the platform used by NC State for managing Help Desk tickets and other support interactions. It’s also an incredibly powerful platform that has the potential to do a lot more than “just support” (and OIT DWS alumnus Jen McFarland now heads the team that’s implementing that service for campus).

Included with ServiceNow is Knowledge, a tool for creating, editing, and organizing knowledge articles and documentation. Knowledge is useful not just because it helps manage information, but because it places that information at the fingertips of the Help Desk. When someone contacts the Help Desk, a new incident is created. When Help Desk staff responds to that incident, ServiceNow automatically prompts them with a knowledge article search based on the short description of that incident. Help Desk staff then also have the option of attaching the text of a relevant knowledge article to their response.

Auto-populated knowledge article search from the short description "How do I get a face covering?"

Using ServiceNow Knowledge to manage COVID-19 information means not only is information centralized, but it’s in the right place to best help staff responding to questions from the campus community. Articles are still being added and refined, but you can view the COVID-19 knowledge portal now.

Bringing it all together in WordPress

Thanks to the hard work of NC State’s ServiceNow team, knowledge articles are now available via a REST API endpoint. (You can request credentials for accessing the API by emailing servicenow@help.ncsu.edu.) From there, WordPress and the NC State Knowledge plugin do the rest.

Once the plugin is activated and configured, you will see two new blocks in the WordPress block editor. (Note: If you’re still using the classic editor, there’s shortcode support too!) Read the detailed documentation on using the plugin for all of the settings available, but I’ll share the highlights below.

Single Knowledge Article

The Single Knowledge Article block displays, well, the content of a single knowledge article. Add the block and enter the unique KBXXXXXX ID number for that article (and configure your preferred layout options) and the contents of the knowledge article display in your post or page.

Single Knowledge Article block settings, including a field to enter a unique ID number.

For example, here’s a knowledge article about transportation services on campus:

Are there any changes to transportation or parking services on campus?

KB0017149

Last Updated: 2020-07-27 18:44:31

The university is making changes to its campus bus system, Wolfline, to help reduce the risk of COVID-19. Drivers and riders will be required to wear face coverings, and some seats will be blocked off to help maintain physical distancing between passengers. Only three passengers will be allowed to stand on the bus. Standing spaces will be marked with floor decals. Riders will enter through the front door only and will fill available seats from the rear to front of the bus. They will exit through the rear door only. Buses will be cleaned daily with an EPA-approved disinfectant. When weather permits, we will open the roof hatches on buses to increase fresh airflow.

NC State will redesign bus schedules, resulting in fewer routes but increased frequency so buses will be less crowded. Students, employees and visitors are encouraged to use the ParkMobile app for short-term parking. For more information, visit the NC State Transportation website.

List of Knowledge Articles

The List of Knowledge Article block displays—you guessed it—a list of knowledge articles. You can filter articles by:

  • Knowledge Base
  • Category within a Knowledge Base
  • “Knowledge REST Sites,” a meta field for arbitrarily grouping across categories

Below are some screenshots for configuring the filters to display all of the articles from a selected category in a selected knowledge base. The options for each knowledge base and category are populated from API calls to ServiceNow, updated every week (and can be refreshed manually).

List of Knowledge Articles block settings, including options for filtering by knowledge base, category, and REST Sites grouping.
Block settings dropdown listing all of the available knowledge bases.
Block settings dropdown listing all of the categories associated with the NC State FAQ knowledge base.

The block also has three main display modes (plus a few additional options):

  • Display articles as a list of links to ServiceNow
  • Display articles with their full text
  • Display articles in collapsible FAQ-style panels

For example, here’s a collapsible panel with all of the articles from the NC State Frequently Asked Questions knowledge base in the category COVID-19 / Travel:

Caching and refreshing data

The NC State Knowledge plugin caches the content of knowledge articles for 60 minutes every time it makes an API call. When data has expired, the plugin makes a new API call to get a fresh copy of the data the next time someone visits a page with knowledge article content on your website.

Caching article content is important because, to be totally blunt, we don’t want to break ServiceNow. If a broadcast email goes to 50,000 members of the campus community—and those 50,000 people click a link to a page with a knowledge article on it—we don’t want to overload ServiceNow with 50,000 API calls in a short period of time. With caching, a page might generate one call per hour.

The 60-minute cache expiration helps ensure that information remains up-to-date and in sync across every website displaying that information. If critical updates are made that can’t wait for that 60-minute expiration, there’s an option available on the plugin settings page to manually refresh the cache ahead of schedule.

A note on accessibility

One of the display options in both blocks is to set a base heading level. That sets the heading level (H1 through H6) for the title of each knowledge article that’s displayed in the block—and if headings are used to divide the article itself into sections and subsections, then those heading levels are adjusted accordingly.

Using proper heading structure is important for accessibility. When you’re layout out your page that’s going to include knowledge articles, pay attention to where you’re inserting your knowledge article blocks. My two example blocks above both sit beneath H3 headings, so I set the base heading level to H4. If you inspect the code of the page, you’ll see that all of the article titles are H4 headings.

Besides heading levels, be aware of any potential content accessibility problems in the article text, like “click here” links or images without alt text.

Other potential uses

Every time I’ve demo’d the NC State Knowledge plugin, it’s felt… kind of anticlimactic. At the end of the day, we’ve put a ton of energy into building a new way to, uh, put some text on a page. It’s not super flashy.

But this is an incredibly important project, and not only for its part in the campus response to COVID-19. Any information that serves a broad campus audience, or that needs to be readily available to Help Desk staff, can live in ServiceNow knowledge articles. That might be answers to common student questions that gets duplicated across many college websites. That might be IT service documentation and troubleshooting, a lot of which lives in the OIT website. That might be information about major campus events like commencement. When information needs to be republished in multiple places, the NC State Knowledge plugin helps you cope with a major communications challenge by letting you create content once and publish it everywhere.