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.
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 firstname.lastname@example.org.) 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.
For example, here’s a knowledge article about transportation services on campus:
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).
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:
Last Updated: 2020-07-27 17:57:06
Travelers, departments, and funders must use their best judgment in deciding what travel they deem to be essential. That involves balancing the benefits of travel with health and safety considerations for themselves and those with whom they may have close contact. In making this determination, students and staff should consult their supervisors; faculty should consult their department chairs.
To aid in the determination we recommend travelers considering the following:
- Is the travel required to fulfill a critical research, teaching, legal, or compliance obligation?
- Is the travel necessary to meet a graduation requirement?
- Can the travel be postponed?
- Is there a substitute to in-person travel such as virtual engagement?
- Can someone in the destination location perform the activity in lieu of you?
For specific expectations, please review the 3D memo.
Last Updated: 2020-07-28 15:25:08
Travelers are expected to follow CDC and US Department of State guidance for returning from travel, which may include 14 days of self-quarantine. Guidance for travelers is evolving and will be updated as appropriate.
Please note that travel for NC State is limited to essential travel only. For more information on travel expectations, please review the 3D memo.
Last Updated: 2020-08-28 16:12:41
The process takes time, so plan ahead. Travel exception requests should be submitted at least two weeks prior to the travel departure date and no sooner than two months in advance. First, you need to have an approved research restart project. You need research approved before you can apply for a travel exception. You need an approved travel exception before you can file a regular Travel Authorization.
If the project requires travel outside of the state, you request an exception through the university travel exception process. Travel exceptions are not required for in-state mileage-only travel or in-state travel with no overnight stay. (talk about that process)
If the exception is approved, you file a normal travel authorization in MyPack Portal that goes through usual approvals.
You can find guidance regarding travel restrictions and exception requests in the 3D memo Travel Exception Process and Required Approvals during COVID-19 Impacted Operations, which includes a link to the Travel Exception Form.
Last Updated: 2020-07-27 19:55:26
All personal international travel is strongly discouraged. If you must travel, consider the potential impacts – self-quarantine upon return, impact on teaching and work obligations if you become ill. For more information follow the CDC and US State Department websites.
Last Updated: 2020-08-28 16:14:08
While there will continue to be restrictions around the number of people allowed in a vehicle, there is an exception process. Use the following form to request exceptions: PPE and Safety Requirements Special Circumstances Request Form.
Last Updated: 2020-07-27 19:10:28
Not at this time. As travel guidance is amended, this may change.
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.