Taxonomies for Confluence

Classify Confluence pages using existing controlled vocabularies, improve search, build better tables of contents and integrate Confluence into knowledge graphs.

Organizations taking on the development of enterprise architecture or implementation of data governance and regulatory compliance may opt for new and expensive specialized documentation management software that requires adoption. They often neglect the existing tools, such as Atlassian Confluence and Jira, already widely used by their teams.

Taxonomies for Confluence

Increase the value of your investment in Confluence by quickly adapting it to software development lifecycle, enterprise architecture, data governance, risk and regulatory compliance documentation management. Taxonomies for Confluence add-on enables:

  • Page classification in Confluence by type, subject and related concepts
  • Use of existing controlled vocabularies and reference data such as capability models, industry classifications, risk and control, or other corporate taxonomies for page classification
  • Tables of contents with type, subject and related concepts
  • Improved search by using preferred and alternative concept labels to search for Confluence content
  • Tracking of documentation coverage
  • Integration of Confluence into knowledge graphs using structured data and SPARQL federated queries.

Frequently asked questions

See Frequently Asked Questions for questions about using existing controlled vocabularies, such as corporate taxonomies, with Confluence, dealing with several user groups using different terms for the same concept, and implementing faceted classification of Confluence pages and blog posts.

Getting started

Start with the development or adoption of existing controlled vocabularies - dictionaries, taxonomies or thesauri - using Simple Knowledge Organization System (SKOS).

For example, when developing an enterprise architecture, you may start with building a common vocabulary of terms such as Business Capability and Business Service (here’s TOGAF 9.2 terms as an inspiration) and developing a taxonomy of business capabilities of your organization (here’s an example of Investment Management Capabilities). Similarly, you can build taxonomies from regulatory rulebooks when working on compliance projects (here’s taxonomy derived from APRA CPG 235 - Managing Data Risk).

Import SKOS concept schemes

Once the Taxonomies for Confluence add-on is installed, new Taxonomies menu is added to the Settings page available to Confluence administrators. It lets you import developed or adopted SKOS taxonomies and use them with Confluence.

Select Taxonomies to navigate to the taxonomies settings page.

Empty taxonomy snapshots

Importing SKOS taxonomies from catalog

To import open-source SKOS taxonomies from the curated catalog, select Import SKOS taxonomies from catalog from the Actions menu. In the Import SKOS taxonomies from catalog dialog select the taxonomies file and click Import selected taxonomies.

Taxonomies currently included in catalog:

  1. Australian and New Zealand Standard Industrial Classification (ANZSIC)
  2. Taxonomy for Policy
  3. Software Development Lifecycle (SDLC) Document Types Taxonomy
  4. TOGAF® 9.2 Architecture Repository Document Types Taxonomy
  5. TOGAF® 9.2 Content Metamodel Vocabulary

Import SKOS taxonomies from catalog

Importing SKOS taxonomies from file

To import SKOS taxonomies from file, select Import SKOS taxonomies from file from the Actions menu. In the Import SKOS taxonomies from file dialog select the file and click Upload and import file. RDF/XML, N-Triples, Turtle, Turtle-star, N3/Notation3, TriX, TriG, TriG-star, binary RDF, N-Quads, JSON-LD, RDF/JSON, RDFa and HDT formats are supported detected from the file extension.

Import SKOS taxonomies from file

Managing taxonomy snapshots

The difference between draft and current taxonomy snapshots is calculated when the upload completes, and updated statistics are displayed in the taxonomy snapshot table. You can explore the contents of each snapshot by clicking on the corresponding row of the taxonomy snapshot table.

Explore imported SKOS taxonomies

To clear the draft taxonomy snapshot, select Clear draft snapshot from the Actions menu. In the Clear draft snapshot dialog, confirm that you want to clear the draft snapshot. When the request completes, the difference between cleared draft and current taxonomy snapshots is calculated, and updated statistics are displayed in the taxonomy snapshot table.

Clear draft snapshot

When you are ready to start using the taxonomies in the draft snapshot with Confluence content, select Start switching to draft snapshot from the Actions menu. In the Start switching to draft snapshot dialog confirm that you want to start switching. When the request completes, the impact on the Confluence content is checked and reported in the taxonomy snapshot table.

Start switching to draft snapshot

To complete the switch, click the Complete switch button. In the case of Confluence content impact, the following actions are taken during the switch to update Confluence content.

SKOS Concept changes Confluence content actions
Concept is removed Type and Subject Confluence content property is removed, and Related Concept macro is replaced with the plain text content of skos:prefLabel property of the SKOS Concept.
Concept is removed with replacement Concept specified using dcterms:replaces property Type and Subject content property and Related Concept macro are updated to reflect URI, skos:prefLabel, skos:altLabel and skos:notation of the replacement SKOS Concept.
Concept properties such as skos:prefLabel, skos:altLabel and skos:notation are updated Type and Subject content property and Related Concept macro are updated to reflect the change in skos:prefLabel, skos:altLabel and skos:notation of the SKOS Concept.

Complete switch

When the taxonomy snapshot switch and Confluence content migration are complete, the updated statistics are displayed in the taxonomy snapshot table.

Taxonomy snapshots

Classify Confluence pages

Once Taxonomies for Confluence add-on is installed, new Type and Subject bylines and Related Concept macro are made available to Confluence users. It enables classification of Confluence pages and blog posts using concepts from imported SKOS taxonomies.

Page classification using type

To classify Confluence page by type, click on the Type byline, search for and click on the concept corresponding to the type of the page (e.g. role description, performance requirements).

Index Confluence Pages

Page classification using subject

To classify Confluence page by subject, click on the Subject byline, search for and click on the concept corresponding to the subject of the page (e.g. regulatory requirement, capability, service, system).

Index Confluence Pages

To classify Confluence page by related concepts, start typing /related anywhere in the body of the page and pick Related Concept from the pop-up Macro menu. Alternatively, click + icon in the editor menu and pick Related Concept from the Macro menu at the top.

Index Confluence Pages

Search for the related concept (e.g. data criticality classification, industry sector) to insert and select the concept from the search results.

Index Confluence Pages

Click Insert to insert the relation. Once the relation is inserted, the URI of the concept, skos:prefLabel, skos:altLabel and skos:notation can be used in Confluence search.

Index Confluence Pages

Inserting table of contents

Start typing /about anywhere in the body of the page where you want to insert the table of contents and pick About and Related from the pop-up Macro menu. Alternatively, click + icon in the editor menu and pick About and Related from the Macro menu at the top.

Insert Table of Contents

Build a set of criteria for pages to be included in the table of contents by selecting whether a concept is a type, subject or a relation of a page, and specifying whether narrower concepts need to be included.

For example, if you imported TOGAF 9.2 and CPG 235 taxonomies and classified Confluence pages using concepts from these taxonomies, creating the table of contents that includes pages that are Role descriptions, are about Data-specific roles and responsibilities and are related to concept of Data quality requires the following set of criteria:

Insert Table of Contents

Click Insert to insert the table of contents.

Insert Table of Contents

Track alignment and gaps

Once the Taxonomies for Confluence add-on is installed, the new Taxonomies App and About and Related macro are made available to Confluence users. They let you track the alignment of Confluence pages and blog posts to controlled vocabularies - dictionaries, taxonomies and thesauri - developed internally, by regulators or standards-setting organizations.

Select Taxonomies item from the Apps menu to navigate to the taxonomies page.

Taxonomies menu item

Expand concepts to see narrower concepts or pages and blog posts that are about or related to these concepts.

Track Alignment

Integrate Confluence into knowledge graphs using SPARQL federation

Use Taxonomies for Confluence SPARQL endpoint to federate structured data across Confluence and other sources such as GitHub or Bitbucket. See Knowledge Graph Descriptor for a structured data example.

Contact us to request access.

Federate structured data across several sources with SPARQL

Use CQL for reporting and integration

Once Taxonomies for Confluence add-on is installed, three additional properties become available in Confluence pages and blog posts: taxonomiesForConfluenceTypeUri and taxonomiesForConfluenceSubjectUri (populated with the URI of SKOS concept set as type and subject respectively), taxonomiesForConfluenceTypePreferredLabel and taxonomiesForConfluenceSubjectPreferredLabel (populated from skos:prefLabel) and taxonomiesForConfluenceTypeNotation and taxonomiesForConfluenceSubjectNotation (populated from skos:notation). These properties can be used in CQL queries allowing you to integrate content or implement reporting using Confluence APIs.

For example, you can use ANZSIC codes in CQL search.

Request:

GET https://dalstonsemantics.atlassian.net/wiki/rest/api/search?cql=taxonomiesForConfluenceSubjectNotation=0806&limit=25

Response:

{
  "results": [
    {
      "content": {
        "id": "1194950668",
        "type": "page",
        "status": "current",
        "title": "BHP",
        "childTypes": {},
        "macroRenderedOutput": {},
        "restrictions": {},
        "_expandable": {
          "container": "",
          "metadata": "",
          "extensions": "",
          "operations": "",
          "children": "",
          "history": "/rest/api/content/1194950668/history",
          "ancestors": "",
          "body": "",
          "version": "",
          "descendants": "",
          "space": "/rest/api/space/FI"
        },
        "_links": {
          "webui": "/spaces/FI/pages/1194950668/BHP",
          "self": "https://dalstonsemantics.atlassian.net/wiki/rest/api/content/1194950668",
          "tinyui": "/x/DIA5Rw"
        }
      },
      "title": "BHP",
      "excerpt": "BHP, formerly known as BHP Billiton, is the trading entity of BHP Group Limited and BHP Group plc, an Anglo-Australian multinational mining, metals and petroleum dual-listed public company headquartered in Melbourne, Victoria, Australia.\nThe Broken Hill Proprietary Company was founded on 16 July 1885 in the mining town",
      "url": "/spaces/FI/pages/1194950668/BHP",
      "resultGlobalContainer": {
        "title": "Fixed Income",
        "displayUrl": "/spaces/FI"
      },
      "breadcrumbs": [],
      "entityType": "content",
      "iconCssClass": "aui-iconfont-page-default",
      "lastModified": "2021-09-22T17:36:48.000Z",
      "friendlyLastModified": "Sep 22, 2021",
      "score": 0.0
    }
  ],
  "start": 0,
  "limit": 25,
  "size": 1,
  "totalSize": 1,
  "cqlQuery": "taxonomiesForConfluenceSubjectNotation=0806",
  "searchDuration": 61,
  "_links": {
    "base": "https://dalstonsemantics.atlassian.net/wiki",
    "context": "/wiki",
    "self": "https://dalstonsemantics.atlassian.net/wiki/rest/api/search?cql=taxonomiesForConfluenceSubjectNotation=0806"
  }
}

Solutions

Talk to us about the development of enterprise architecture vocabularies and regulatory and compliance taxonomies, and integrating Taxonomies for Confluence into your environment.

Attributions

This user guide uses material from the Wikipedia Data Steward and BHP articles, that are released under the Creative Commons Attribution-Share-Alike License 3.0.