How to use URLs with the Visio Viewer macro to render Visio files

This article discusses the recommended way of using URLs, especially in correlation with profiles, in the URL to Visio file parameter of the Visio Viewer macro. URLs are used to access Visio files in remote locations and applications, including those applications linked with Confluence, such as GitLab, GitHub, Microsoft OneDrive and so on.

1 Types of URLs used in the Visio Viewer macro 1.1 Precedence in URL processing 2 Usage of URLs and profiles in the macro 3 How it all works 3.1 Profile configuration 3.2 Macro editor settings 4 Points to remember 5 Additional links

1 Types of URLs used in the Visio Viewer macro 1.1 Precedence in URL processing 2 Usage of URLs and profiles in the macro 3 How it all works 3.1 Profile configuration 3.2 Macro editor settings 4 Points to remember 5 Additional links

This page also contains more information about the URLs that can be given, the order used to process URLs, and finally, how URLs must be used with profiles in the macros.

You can connect to an external application or location through a URL and display relevant Visio content on your pages. For this purpose, the Visio Viewer macro allows you to use profiles and URLs to specify the complete path to access the required application data. It is recommended to specify both, a profile with a base URL and a relative path in the URL to Visio file field, in the macro configuration. This way, you can access multiple locations through the same profile, and render Visio content on your pages.

Contact your Confluence administrator to understand which profiles are available in your instance.

Types of URLs used in the Visio Viewer macro

First, it is important to understand how the macro processes URLs. A URL provided in a macro can be:

an absolute URL that can be used to access the relevant Visio file,
a relative path to the actual location of the file to be rendered, or,
an application link (a link between Confluence and an external application such as Bitbucket).

Verify these points about the URL!

If a URL is entered in URL to Visio file, without specifying any profile or an application link, ensure that:

Only a raw URL is given to access Visio files from a remote location. A raw URL is defined as the part of the URL following the domain information and includes the query string, if present. For example, in the URL string http://www.contoso.com/articles/recent.aspx, the raw URL is /articles/recent.aspx.
The URL can access Visio files on public, remote locations. For example, if a URL is given to access a Visio file from a Bitbucket repository, the repository must be public. Thus, user credentials need not be given so that the macro can easily access the specified location and render the relevant file.

If these points are not followed and the macro is unable to either process the given URL or access the given location, relevant errors are displayed.

Precedence in URL processing

URLs given in the macros are processed in the following order as explained:

Priority given	URL type	Description

Priority given	URL type	Description
1	Application links	If the given URL is linked to a specific application like Bitbucket, the macro does not require any user credentials and renders the specified file. Refer to this article about application links for information.
2	Profiles	If Profile is specified, the macro appends the URL given in URL to Visio file to the URL specified in the profile configuration, and accesses the location to render the required file.
3	Simple URLs	Lastly, if no application links or profiles are given and just an absolute URL is given, the URL is processed as-is and the required file is rendered. Note that the specified URL must point to a public resource; else, it is recommended to create and use a profile to access any private location.

Usage of URLs and profiles in the macro

The correlation between URLs and profiles with respect to the macro can be explained as:

Is Profile given? (Y - Yes, N - No)	Is Location given? (Y - Yes, N - No)	Macro behavior

Is Profile given? (Y - Yes, N - No)	Is Location given? (Y - Yes, N - No)	Macro behavior
Y	N	Accesses the URL specified in the profile through the pre-configured information.
N	Y	Accesses the URL specified and renders the Visio content as required.
Y	Y	Appends the URL mentioned in the URL to Visio file parameter to the URL configured in the profile. Thus, the macro(s) creates an absolute path to the required file. If this path is not valid, a network error message is displayed. To resolve this issue, contact your Confluence administrator for more information.

How it all works

Profile configuration

For this example, let’s assume a profile is created as follows:

Create profile

Points to note in the screenshot:

Here, the profile is to be linked with Bitbucket and the base URL of the application is to be entered in the URL field.
The macro uses the given User and Password parameters to access the location specified in the URL to Visio file parameter in the macro editor. You can also provide access tokens, if applicable. An access token works almost like a direct link to the specified URL and thus, does not require user credentials. See the profile configuration documentation for more information.

Macro editor settings

After the profile is created, it must be specified in the macro along with the path to the Visio file to be rendered.

Create or edit a page, add the Visio Viewer macro, and edit to open the macro editor.
Select the relevant profile from the Profile drop-down.
Enter a relative path (partial URL) to access the required Visio file in URL to Visio file.
Visio Viewer macro with profile settings
Save the macro and publish the page to see the content.

Points to remember

Only raw URLs must be given and any absolute URL must point to a remote location that is accessible without user credentials. For example, a raw URL that can access a Visio file in a public Bitbucket repository is valid. But to render a Visio file located in a private repository, we recommend using a profile.
Profiles are a means to access and retrieve contents from external applications such as Bitbucket. A profile already contains the base URL and the required credentials (user credentials or an access token) to access the relevant application.
If a URL that links to another application linked with Confluence is provided, the macro recognizes such URLs and renders the specified Visio file without asking for user credentials. The macro asks for user credentials only for the first time that it tries to connect with the linked application.
If a profile is specified in the macro editor, enter a relative path in the URL to Visio file field to access the required file(s).
If an absolute URL is entered in the URL to Visio file field, the macro can directly access the file(s) in the specified path; given that the file is in a public location that does not require user credentials to be accessed.