Add-on to extend the projectdoc Toolbox to integrate remote information systems.

The extension to the projectdoc Toolbox provides macros to link to and transclude from pages on remote servers.

Typically links to remote servers are fully qualified when copied to a Confluence page. This makes it difficult or cumbersome to change the URL at a later time. For instance the URLs to an API documentation may contain a version information or the URL to the server providing architecture view images changes. The macros provided by this extension makes it easy to deal with such changes by externalizing path prefixes with space properties.

Contents

Categories of Macros
Macros
Services
Autoconverting
- How it works
- Configuration
Authentication
Space Properties
Resources

Categories of Macros

There are three kinds of macros in this extension. Macros that

help to integrate by identifying domain information
reference or transclude image and text information
reference or transclude text information with explicit URL

The first two versions have in common that the base link is configured at space level (or at site level using the Delegate Space feature). The third category provide tools to access remote information at an individual basis with explicitly specifying the URL.

Domain References

The macros make it easier to link to resources on remote servers. The link is specified in form of a domain specific value, not as a plain URL.

The Javadoc Link Macro allows to create a link to information in the API documentation by specifying the class or method.
Java Elements in Javadoc
To reference the a class, specify the name of the class like this:

com.example.something.MyClass

The following example references a method aMethod():

com.example.something.MyClass.aMethod()

Here an example referencing a method aMethod(String, Class<?>) with generics:

com.example.something.MyClass.aMethod(java.lang.String, java.lang.Class)

Note to specify the parameters fully qualified and that generic type parameters or wildcards are not part of the reference.
Reference to a view on the model create by the Enterprise Architect are created via the Image ID with the Enterprise Architect Image Link Macro.
The Nexus Link Macro renders links to artifacts with group, artifact, and version information.
The macro body contains the reference to the artifact.
This is the rendered short link:
The rendered XML code looks like this:
In this example the title is a link to the artifact on the Nexus server.

Generic Macros

Specify references to images and text based on systems specified at space level.

Use the placeholder feature to create reusable and maintainable space properties.

Explicit URL

Macros allow to transclude by specifying the URL explicitly.

Text Snippet Macro

Macros

The extension provides the following macros to specify links or transclusions to remote resources.

#	Name	Short Description
1	Enterprise Architect Image Link Macro	Renders an image generated from an Enterprise Architect diagram, transcluded from a server.
2	HTML Snippet Macro	Transclude HTML content from a remote server.
3	Javadoc Link Macro	Links API documentation pages for Java elements.
4	Nexus Link Macro	Renders a link to an artifact stored on a Nexus server.
5	System Image Link Macro	Renders an image transcluded from a remote server.
6	System Link Macro	Links to a resource on a server.
7	System Transclusion Macro	Transclude content from a resource from a remote system.
8	Text Snippet Macro	Transclude text content from a remote server.

The following macros are deprecated since version 1.0 and will be removed soon. Please use the System Link Macro instead.

#	Name	Iteration	Short Description
1	Hudson Link Macro	Deprecated	Render links to jobs and services on a Hudson server.
2	Site Link Macro	Deprecated	Links to a resource on a versioned site.
3	Sonar Link Macro	Deprecated	Renders a link to a project on a Sonar service.
4	Subversion Link Macro	Deprecated	Renders a link to a resource on a Subversion (SVN) repository.
5	Subversion Transclusion Macro	Deprecated	Transcludes a snippet from a project on a Subversion (SVN) server.

The macros supported users to parametrize locations. Since space properties have the placeholder feature built in since version 1.11 of the projectdoc Toolbox, the configuration is now much simpler.

Services

The extension provides the following services and components.

#	Name	Since	Short Description
1	URI Autoconverter	1.0	Autoconvert URLs to Macros of the Information Systems Extension.

Autoconverting

Keeping references to external systems up-to-date is a difficult task. It is to some degree easier to reference systems that are external to the Confluence server, but still in control of the team managing the documentation and communication infrastructure. None-the-less external information systems may change addresses. To change all references to an external information system easily, the Information Systems Extension provides macros to derive the base URI from a central configuration on the Confluence server. The autoconvert service enhances the usability of these macros by creating them on the user's paste action.

How it works

The macros of the Information Systems Extension use base URIs defined as space properties, shortcuts, or application links (see System Identifier to URI Resolution Algorithm for details). The macros are specialized or generic, as explained in Categories of Information System Macros.

By pasting an URL to a page the autoconvert service checks for the appropriate macro based on the pasted URL. The identification process has to take into account that not all URIs have to be autoconverted. That is the URI needs to match a specific pattern to uniquely identify the macro or determine that none of the macros match. Therefore it is recommended to associate the URI with a specific matcher by name with the space property

This information is reused by the Autoconvert component. The Autoconvert component tries to derive the appropriate macro.

HTML Title as Link Label

Since version 1.2 the Autoconvert component reads the DC.title header or the HTML title to set the label for the macro.

Configuration

The configuration of the autoconverters is conducted in two steps:

Define the information system(s)
Map information system(s) to autoconverters

Define Information Systems

Define your information systems by binding an identifier to an URI. This binding may either be defined as a space property, a shortcut, or an application link.

If the information system macro defines a default system identifier, it is recommended to use this identifier for the binding. Users then do not need to type the identifier to the macros explicitly.

In situations where this system default identifier is already in use in a space with a different meaning, use the following syntax to specify the system with a space property:

url-{system-id}

The key with the url-Prefix is always checked first.

Space Properties

The following examples shows the definition of three information systems as space properties.

Map Information Systems

Use the space property Autoconvert Hint to bind autoconverters to information systems.

Check if the default configuration (as specified in Autoconvert Hint) will work for you. This is especially the case if you do not use the generic information systems to link to images or text resources.

If you can go with that configuration is much simpler - since nothing has to be done.

Note that if you specify one system, default systems are no longer defined.

Specify the Hint

The following examples shows how to bind information systems by their identifier to autoconverters.

Whenever a user pastes in the given space an URI with the prefix https://build.example.com/images/xmi an instance of the Enterprise Architect Image Link Macro is created. URIs with the prefix https://scs.example.com/images are stored in a System Image Link Macro.

Since 1.4

Since version 1.4 the link type is per default 'link', if not specified.

The old version, where the type matches the name can still be used if the hint ends with ':'. This will just save some typing since my-id: is the same as my-id:my-id.

Whitelist

Since the Confluence Whitelist restricts access to remote servers. URLs that are not listed in the Whitelist cannot be accessed from the Autoconvert code. Therefore all URLs configured for the projectdoc Autoconvert need also be added to the Whitelist.

Configuring the Whitelist, as part of the Confluence documentation by Atlassian, shows how to allow access to remote servers.

For the projectdoc Autoconvert only access to the remote system is required. The remote system does not access the Confluence server for this feature.

When pasting an URL to a Wikipedia article, the autoconverter will create a macro for the link.

The rendered macro will show the title of the article as its label instead of the URL.

Authentication

Since version 1.4 of the Information Systems Extension the autoconverter service and transclusion macros (System Transclusion Macro, Text Snippet Macro, and HTML Snippet Macro) use the Application Links configured in Confluence to access remote resources.

Impersonating OAuth

Impersonating OAuth using Application Links is supported.

The URL configured with projectdoc (for example as a space property using the url- prefix) needs to find a prefix URL configured as an application link. So the URLS of the system link and the Application Link have to match, not the prefix of your defined url-property and the name of the Application Link The first match is used to authenticate to access a protected resource on the remote service.

Example

Definition of the space property:

Definition of the Application Link

So the value of the property url-Jenkins mapps to the Display URL of the Application Link

OAuth

Currently not supported.

Basic Authentication

Basic authentication using HTTP headers is supported.

A Basic Authentication Link is also established using the Application Links admin page.

This time you do not create an impersonating OAuth Link but an Application Link with Basic Authentication.

Example

Create an Application Link and fill in the URL → press "Continue"

Fill in the "Application Name" and press "Continue".

Edit the "Application Link" by clicking the "pencil" icon.

Choose "Outgoing Authentication" and there "Basic Access" and fill in "Username", "Password" and "Confirm Password".

Save.

Space Properties

The extension defines the following space properties.

ID	Short Description	Default Value	Since
`projectdoc.extension.information-systems.autoconvert.check-resources`	Set the default value for macro parameters controlling the checking of the referenced resource.	`false`	3.1
`projectdoc.extension.information-systems.code.attachment.title-strategy`	Controls the title shown in code boxes rendered by macros in the Information Systems Extension.	`file-name`	3.1
`projectdoc.extension.information-systems.transclusion.lines`	Set the default value for selecting on line numbers.		3.1

Resources

Related information on the information system extension.

Autoconvert Information System URIs: Introduction to the autoconvert feature for URIs to external systems.
Categories of Information System Macros: Overview over the different categories of macros that are part of the Information Systems Extension.
Confluence as the Information Hub: Tools from the projectdoc Toolbox to import from and export to other information systems.
Information System Macros: List of macros linking to or transcluding from external information systems.
System Identifier to URI Resolution Algorithm: Describes how the system calculates the URI to an information system based on its identifier.