Add-on to extend the projectdoc Toolbox to integrate remote information systems.
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.
- 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.
Autoconverting
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
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
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.
