Autoconvert Information System URIs

Versions Compared

Old Version 1

changes.mady.by.user Robert Reiner

Saved on 01. May 2016

compared with

New Version Current

changes.mady.by.user Robert Reiner

Saved on 31. Dec 2019

Key

This line was added.
This line was removed.
Formatting was changed.

...

Section

Column

Document Properties Marker

override	false

Short Description	Introduction to the autoconvert feature for URIs to external systems.


Doctype	topic	hide
Name	Autoconvert Information System URIs

Parent

Parent Property

property	Parent
property-name	Name

Audience

Name List

doctype	role
render-no-hits-as-blank	true
names	Author, Documentation Architect, Documentation Gardener
property	Audience
empty-as-none	false

Level of Experience

Name List

doctype	experience-level
render-no-hits-as-blank	true
property	Level of Experience

Expected Duration

Subject

Name List

doctype	subject
property	Subject

Sponsors

Name List

doctype	stakeholder
render-no-hits-as-blank	true
property	Sponsors

Extension

Information Systems Extension


Since	1.0


Sort Key		hide

Column

Panel

title	Contents

Table of Contents

indent	10px
exclude	Autoconvert Information System URLs
style	none

...

Section

title	How it works
tags	content

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.

Note Box

title	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.

Section

title	Configuration
tags	content

The configuration of the autoconverters is conducted in two steps:

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

Section

title	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.

Tip Box

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:

Code Block

language	text

url-{system-id}

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

Example Box

title	Space Properties

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

Section

title	Map Information Systems

Use the space property information-system-autoconvert-hint Autoconvert Hint to bind autoconverters to information systems.

Tip Box

Check if the default configuration (as specified in information-system-autoconvert-hint 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.

Example Box

title	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.

Version Box

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.

Section

title	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.

Image Added

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

Image Added

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

Image Added

Section

title	Authentication

Transclusion

document	Authentication with Information Systems Extension
ids	Authentication

Section

title	Own Autoconverters

With the autoconverter feature of the information systems extension for the PDAC1, 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.

Note Box

title	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.

...

Section

title	Limitations on Autoconverters

The following limitations apply for uses of the autoconverters.

Section

title	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.

Section

title	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.

Tip Box

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

Jira

server	smartics JIRA
serverId	79ad43bc-d289-364e-bfc7-46c09847bebd
key	PDEXINFOSY-6

is resolved.

Section

title	No Single Quotes

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

See

Jira

server	smartics JIRA
serverId	79ad43bc-d289-364e-bfc7-46c09847bebd
key	PDEXINFOSY-19

Section

title	Subordinate Topics

Display Table

doctype	topic
render-no-hits-as-blank	true
select	Name, Short Description
restrict-to-immediate-children	true
sort-by	Sort Key, Name

...

Section

title	Resources

More information related to autoconverting URIs and information systems.

Tour

render-as-definition-list	true
replace-title-with-name	true

Title	Short Description
System Identifier to URI Resolution Algorithm

information-system-autoconvert-hint

Information Systems Extension


Autoconvert Hint

Categories of Information System Macros


/ Information Systems Extension	Overview over related resources.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 1

New Version Current

Key

About

Keep up-to-date!

Powered by