Versions Compared

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

...

Warning

Removal notice:

Please note that the URL user and URL user password parameters were removed in 5.8.5 (see Deprecation notice: URL user and URL user password parameters). We recommend using profiles to access external data.

This article illustrates how to create a profile in the macros using a URL to be used with any of the HTML for Confluence macros.

Table of Contents
minLevel2
maxLevel6
outlinefalse
styledefault
typelist
printabletrue
Info

Before you begin:

  • Before you enter the URL for a repository, ensure that it

    complies with the REST standards published by GitHub or GitLab.
  • Click here for more information on REST Pattern for GitLab.
  • Click here for more information on REST Pattern for GitHub

    is a raw URL. 

    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

    Tip

    Paste the file link into your browser's address bar. If the actual code is displayed in the browser, it is considered to be invalid or in an incorrect format. If the file downloads to your system, the macros can process the file and its contents.

  • Know what is a complete URL.

    • A typical path for the raw file on

    GitLab
    • Bitbucket looks like:

    • /projects/:id/repository/files/:file_path/raw

    • The host address (base URL) begins with:

    • https://

gitlab
    • bitbucket.workspace.com

/api/v4
    • The complete URL, in this example, looks like: 

    • https://

gitlab
    • bitbucket.workspace.com/

api/v4/
    • projects/:id/repository/files/:file_path/raw?ref=master

  • For illustrative purposes, we have used a public Bitbucket

    public repository.

    repository. Use URLs to add to profiles and in macros as per your requirement and your instance. The process for adding a profile and using it in macros remains the same for other repositories and external sources.

There are three two ways to work with URLs where you can use:

Info

For this example, let's

...

use the Html-bobswift macro to illustrate profile creation and usage. The screenshots illustrate where the relevant parameters are to be given. Specify information in the profile window and macro editor as per your requirement in your instance.

Anchor

...

html_

...

57_HowTo_CompleteURL

...

html_

...

57_HowTo_CompleteURL
Using an absolute URL in a profile

...

titleTry this for newer Confluence versions

You can create a profile by providing the complete URL for the HTML/XML content.

Navigate to CONFLUENCE ADMINISTRATION > Settings > ATLASSIAN MARKETPLACE > HTML > Profiles.

in the macro editor.

  1. Select Image Modified > Manage apps, either search for HTML for Confluence or scroll to Bob Swift Configuration, and click HTML to view app configuration.

Tip

Try this for older Confluence versions!

Navigate to CONFLUENCE ADMINISTRATION > Settings > ATLASSIAN MARKETPLACE HTML > Profiles.

  1. Click Add Profile.

  2. Enter a unique name for the profile in the Profile name text box.

...

  1. Select URL from the options in Profile type

  2. Enter 

...

  1. an absolute URL of the location to be accessed in the URL text box. 

  2. Click Save profile to create the profile.

...

  1. Image shows how to add a profile with absolute URL.Image Added

To use this profile in a Confluence page:

  1. Add the

...

  1. Html-bobswift macro or edit an existing macro on the page.

...

  1. Select the newly created profile from the Profile list and then, click Save.

...

Image Removed        

  1. Image shows how to add a profile to the Html-bobswift macro.Image Added

Anchor

...

html_

...

57_HowTo_FixedURL

...

html_

...

57_HowTo_FixedURL
Using a partial URL in a profile

...

titleTry this for newer Confluence versions

You can create a profile by providing a partial URL to access the remote location and entering the relative path to the relevant file in the HTML macro.

Navigate to CONFLUENCE ADMINISTRATION > Settings > ATLASSIAN MARKETPLACE > HTML > Profiles.

the macro editor.

  1. Select Image Modified > Manage apps, either search for HTML for Confluence or scroll to Bob Swift Configuration, and click HTML to view app configuration.

Tip

Try this for older Confluence versions!

Navigate to CONFLUENCE ADMINISTRATION > Settings > ATLASSIAN MARKETPLACE HTML > Profiles.

  1. Click Add Profile.

  2. Enter a unique name for the profile in the Profile name text box.

...

  1. Select URL from the options in Profile type

  2. Enter 

...

  1. the base URL in the URL text box. A base URL is a part of the path that specifies the location that the macro must access.

  2. Click Save profile to create the profile.

...

To use this profile in a Confluence page:

  1. Add the 

...

  1. Html-bobswift macro or edit an existing macro on the page.

...

  1. Select the newly created profile from the Profile list in the editor.

  2. Enter the relative path

...

  1. of the HTML file in the Location of HTML data parameter. The relative URL is appended to the base URL specified in the profile to create an absolute path to the file to be rendered.

  2. Click Save.

...

        Image Removed

...


  1. Image Added

Info

Points to remember!

  • Only raw URLs must be given in either, the URL field in profiles or the Location fields, in the macros.

  • It is recommended to specify absolute URLs to access files from public locations and to use profiles to access files from private sources. For example, a raw URL that can access an HTML file in a public Bitbucket repository is valid. But to render an HTML 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, GitLab or GitHub. A profile already contains the base URL and the required credentials (user credentials or an access token) to access the relevant application.

  • This method allows multiple users to access a profile across pages and instances of the macros.

Helpful resources