This article discusses the recommended way of how URLs must be used in correlation with profiles in the HTML and XSLT macros. The best practice is to specify both, profile and a relative path, in the macros' configuration. In this way, you can access multiple locations through the same profile, and render HTML or XML content on your pages.
Description
You can connect to an external application or location through a URL and display relevant content on your page. For this purpose, the macros allow you to use profiles and URLs to specify the complete path to access the required application data.
Contact your Confluence administrator to know which profiles are available in your instance.
First, it is important to understand how the macro behaves with profiles and URLs. 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 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
For this example, let’s assume the profile has the following values specified:
Here, the profile is linked to GitLab and the URL shown is the base URL of the application that the macro fills automatically.
See the 70629097 section for more information about GitHub and GitLab profile creation.
Create or edit a page, add the HTML macro for this example, and, edit it to open the macro editor.
Enter a relative path (partial URL) to an attachment in Location to HTML data.
As mentioned, the macro appends the relative path in the Location of HTML data with the base URL given in the profile. If this path is valid, the file(s) are read and the HTML content is displayed, else, a network error is displayed.
Save the macro and publish the page to see the content.
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 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 a profile or a URL in the macro editor.
- If you specify an absolute URL in the Location fields, the macro accesses the content in the specified path.
- Take a look at the existing documentation such as the user guide and the administrator guide to know more about the macro itself and its usage.
