Versions Compared

Old Version 7

changes.mady.by.user Smita Nair

Saved on

compared with

New Version Current

changes.mady.by.user Smita Nair

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Modified contents as per style guide, changed to new editor and fixed links

This article discusses the recommended way of using URLs, especially in correlation with profiles, in the HTMLHtml-bobswift and XSLT macros. 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.

Table of Contents
minLevel2
maxLevel6
outlinefalse
styledefault
typelist
printabletrue

You can connect to an external application or location through a URL and display relevant HTML/XML content on your pages. For this purpose, the macros allow you to use profiles and URLs to specify the complete path to access the required application data. The  The best practice though, is to specify both, a profile with a base URL and a relative path in the Location fields in the macros ' configuration. This way, you can access multiple locations through the same profile, and render HTML/XML content on your pages.

Info

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

Click any of the links to know more:

Anchor
html_57_tutl_URLProfiles_types
html_57_tutl_URLProfiles_types
URLs in macros

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

  • an absolute URL that can be used to access the relevant HTML/XML 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

    and another Atlassian application such as Bitbucket

    , GitLab,

    or

    GitHub

    Jira).

Anchor
html_57_tutl_URLProfiles_order
html_57_tutl_URLProfiles_order
Precedence in URL processing

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

Priority given

URL type

Description

1

Application links

If the given URL is linked to a specific application like Bitbucket

, GitLab,

or

GitLab

Jira, the macro does not require any user credentials, and processes and renders the given file. Refer to

 this article 

application links for information

about application links

.

2

Profiles

If 

If Profile

 is

 is specified, the macro appends the URL given here with 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 were given, the URLs are processed as-is and the required file is rendered.

Anchor
html_57_tutl_URLProfiles_profiles
html_57_tutl_URLProfiles_profiles
Importance of URLs with respect to profiles

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

Y

N

Accesses the URL specified in the profile through the pre-configured information.

N

Y

Accesses the URL specified and renders the HTML or XML content as required.

Y

Y

Appends the URL mentioned in the Location of HTML data or Location of XML data 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.

Anchor
html_57_tutl_URLProfiles_working
html_57_tutl_URLProfiles_working
How it all works

Profile configuration

For this example, let’s assume the profile has the following values specified:Image Removed

...

Note

  • Here, the profile is to be linked with GitLab and the

    base URL

    base URL of the application is

    taken automatically

    taken automatically in the URL field. This URL is editable and can be changed according to your requirement.

  • In the given screenshot, an Access token is provided whereas the User and Password parameters are left empty. This is because the 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 about access tokens.

  • See

    the 

    the Additional links section for more information about profile creation. 

Macro editor settings

...

  1. Create or edit a page, add the 

...

  1. Html-bobswift macro (for this example), and edit to open the macro editor.

  2. Select the relevant profile in Profile.

  3. Enter a relative path (partial URL) to

...

  1. access the required file in Location to HTML data.

...

  1. Image Added
    Note

    As mentioned, the macro appends the relative path in the Location of HTML data with the base URL given in the profile. If this

...

  1. absolute

...

  1. path is valid, the specified file is read and the HTML content is displayed, else, a network error is displayed.

  2. Save the macro and publish the page to see the content.

title
Info

Points to remember:

  • Profiles are a means to access and retrieve contents from external applications such as GitHub, GitLab, and so on.

  • A profile already contains the base URL and the required credentials (user credentials or an access token) to access the relevant application.

  • If you specify a profile in the macro editor, enter a relative path in the Location fields to access the required file(s).

  • You

    must specify

    must specify a profile or a URL in the macro editor.

  • If you specify an absolute URL

    in the 

    in the Location fields, the macro can directly access the file(s) in the specified path.