Classify Confluence pages using existing controlled vocabularies, improve search, build better tables of contents, capture structured data alongside other content and integrate Confluence into knowledge graphs.
Taxonomies for Confluence is no longer offered for sale on Atlassian Marketplace. Source code is available under MIT license from Github Taxonomies for Confluence Repository.
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 and to capture structured data alongside other user content
- Building of 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
- Using SPARQL to query indexed Confluence content and bring data from external SPARQL endpoints
- 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 and Schemas menu is added to the Settings page available to Confluence administrators. It lets you import SKOS taxonomies and RDFS schemas and use them with Confluence. You must import a SKOS taxonomy or an RDFS schema first.
Select Taxonomies and Schemas to navigate to the taxonomies settings page.
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 and schemas currently included in catalog:
- Australian and New Zealand Standard Industrial Classification (ANZSIC)
- Taxonomy for Policy
- Software Development Lifecycle (SDLC) Document Types Taxonomy
- TOGAF® 9.2 Architecture Repository Document Types Taxonomy
- TOGAF® 9.2 Content Metamodel Vocabulary
- W3C® RDF Concepts Vocabulary (RDF)
- W3C® RDF Schema Vocabulary (RDFS)
- Schema.org
- Data Governance Scheme and Taxonomy
Importing SKOS taxonomies and RDFS schemas 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.
The size of the file is currently limited to 10MB regardless of the format.
Managing snapshots
The difference between draft and current snapshots is calculated when the upload completes, and updated statistics are displayed in the snapshot table. You can explore the contents of each snapshot by clicking on the corresponding row of the snapshot table.
To clear the draft 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 snapshots is calculated, and updated statistics are displayed in the snapshot table.
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 snapshot table.
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. |
When the snapshot switch and Confluence content migration are complete, the updated statistics are displayed in the snapshot table.
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).
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).
Page classification using related concepts
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.
Search for the related concept (e.g. data criticality classification, industry sector) to insert and select the concept from the search results.
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.
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.
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:
Click Insert to insert the 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.
Navigating taxonomies and pages related to concepts
Select Taxonomies item from the Apps menu to navigate to the taxonomies page.
Expand concepts to see narrower concepts or pages and blog posts that are about or related to these concepts.
Creating statements about a page using RDFS Properties and Confluence tables
Once the Taxonomies for Confluence add-on is installed, the new Resource macro is made available to Confluence users. Resource references can be inserted anywhere on the page. When RDFS Property is placed in the first column of a table without a header row, and RDFS Classes, SKOS Concepts or other resources, macros (dates, links and mentions) and text are placed in subsequent columns, each row is translated into an RDF Statement about the page.
To insert a Resource reference (SKOS Concept, RDFS Class or RDFS Property), start typing /resource anywhere in the body of the page and pick Resource from the pop-up Macro menu. Alternatively, click + icon in the editor menu and pick Resource from the Macro menu at the top.
Search for the resource to insert the reference and select the resource from the search results.
Click Insert to insert the resource reference.
Creating new statements using RDFS Class
To set RDFS Class of the page, click on the Class byline, search for and click on the RDFS Class corresponding to the class of the page (e.g. Place, Corporation, Critical Data Element, Data Container, Concept).
Creating new statements using RDFS and Confluence tables
When RDFS Properties are placed in the header row of a table, and RDFS Classes, SKOS Concepts or other resources, macros (dates, links and mentions) and text are placed in rows, each row is translated into several RDF Statement about a new resource linked to a page.
Using stable identifiers for RDFS statements
Use any link in the first column of the table for stable identifiers that can be referenced from the same or other Confluence pages.
Other Confluence content such as comments can be used alongside structured data.
Querying pages and resources with SPARQL
Once the Taxonomies for Confluence add-on is installed, the new SPARQL macro is made available to Confluence users.
To insert a SPARQL query, start typing /sparql anywhere in the body of the page and pick SPARQL from the pop-up Macro menu. Alternatively, click + icon in the editor menu and pick SPARQL from the Macro menu at the top.
Enter SPARQL query.
Click Insert to insert the SPARQL query and view results.
Federated SPARQL queries
Use SERVICE keyword to integrate data across open access or proprietary SPARQL endpoints.
Import schemas such as schema.org.
Use default bindings to bring data from Confluence into queries. Resource corresponding to the current Confluence page or blog post is bound to this.
Bring in results from remote SPARQL endpoints.
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.
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.
