Introduction to the autoconvert feature for URIs to external systems.

Audience

Categories

/ projectdoc / Extension / Information Systems Extension

Type

Article

Extension

Information Systems Extension

Since

1.0

Contents

How it works
Configuration
Authentication
Own Autoconverters
Limitations on Autoconverters
Resources

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.

The following authentication methods are supported:

Impersonating OAuth (recommended)
Basic Authentication (useful for non-Atlassian servers that do not provided OAuth)

Own Autoconverters

With the autoconverter feature of the information systems extension for the projectdoc Toolbox, users can define their own autoconverters easily.

Just follow the configuration steps and you are done. Whenever an author pastes an URI based on the URI of your information system, the converter will create a system macro and link to the resource.

Use Specifiers

Note that only specifiers allow to map to generic servers. So if your information systems is identified by my, then the specifier should be my:image for image resources and my:link for other (typically text) resources.

Limitations on Autoconverters

The following limitations apply for uses of the autoconverters.

No formatted Text

Autoconvert typically only works on plain text. That is: if the pasted text is formatted (say type writer font), the text will not be recognized.

This is typically not a problem since URIs are copied from the browsers address bar or via the browser's context menu.

No Spaces

If the URI pasted to the editor contains a space, the macro will not get the whole URI.

This is because of the base library provided to integrate autoconverters.

If the space is replaced by a '+' sign or is encoded ('%20'), everything works as expected. But the quickest workaround would be to copy the parameter list into the body until the issue PDEXINFOSY-6 - Autoconverter cannot deal with Spaces To Do is resolved.

No Single Quotes

If the URI pasted to the editor contains a single quote ('), the autoconverter will not be called.

See PDEXINFOSY-19 - Autoconverter cannot deal with Single Quotes To Do .

Resources

More information related to autoconverting URIs and information systems.

System Identifier to URI Resolution Algorithm: Describes how the system calculates the URI to an information system based on its identifier.
Information Systems Extension: Add-on to extend the projectdoc Toolbox to integrate remote information systems.
Autoconvert Hint: List of space property names that refer to a remote information system URL. Elements of the list may be specifier with a system ID and a system type.
Categories of Information System Macros: Overview over the different categories of macros that are part of the Information Systems Extension.
/ projectdoc / Extension / Information Systems Extension: Overview over related resources.

Autoconvert Information System URIs