Using the SharePoint Link Macro

You can use the SharePoint Link macro {sp-link} to put a link on a Confluence wiki page, pointing to a SharePoint list, document or list item. When someone clicks the link, the SharePoint list or document will open. The macro supports most SharePoint list types.

On this page:

Usage with the Macro Browser

The 'Macro Browser' is a graphical menu that allows you to view the list of available Confluence macros and add them to the current page or blog post.

To insert the SharePoint Link macro into a page using the Macro Browser,

Go to the Confluence page or blog post where you want to display the SharePoint link.
Click the 'Edit' button. The page or blog post opens in edit mode.
Click the Macro Browser icon on the toolbar.
The macro browser window opens. Find the 'SharePoint Link' macro:
- Scroll through the list of macros, or
- Start typing the macro name into the search box at the top right of the macro browser window. Macros with a matching name will appear in the main pane.
Click the macro to access its parameters and preview the macro output.
Enter the macro parameters. See the parameter descriptions below.
If you would like to preview your changes, click 'Refresh'.
Click 'Insert' to add the macro to the page.

Usage with the Wiki Markup Editor

Quick guide to the SharePoint Link macro

Using the simplest form of the macro, all you need to enter is the name of your SharePoint list or document library, and optionally the path to a document. The SharePoint Link macro will create a hyperlink on your page, pointing to the SharePoint location or file specified.

Enter the following text onto the Confluence page to link to a list:
```
{sp-link:LIST-NAME}my hyperlinked text{sp-link}
```
Or enter the following text to link to a specific document:
```
{sp-link:LIBRARY-NAME/DOCUMENT-NAME}my hyperlinked text{sp-link}
```
Replace the text 'LIST-NAME' with your own values for your SharePoint list name, or replace the text 'LIBRARY-NAME/DOCUMENT-NAME' with your SharePoint document library and file name.
Replace the text 'my hyperlinked text' with the words that you want displayed as a hyperlink on the Confluence page.

In the example below, we link to a specific document in a SharePoint document library. The library name is 'documents' and the document name is 'checklist.docx'.

What you need to type	Hyperlink created
{sp-link:documents/checklist.docx}a good checklist{sp-link}	a good checklist

Note: Unlike the SharePoint List macro, this macro does not allow you to specify a SharePoint site. The SharePoint Link macro will use the default SharePoint site, as specified in the SharePoint Admin settings. See the Confluence SharePoint plugin configuration guide.

Parameters

Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).

Parameter

Default

Description

listname
(listName)

No default

The first parameter ('listName') can contain the name of a SharePoint list, the name of a SharePoint document library, or the path to a document within a document library. The text 'listName' is optional.

The following example creates a link to the SharePoint document library called 'documents'. The linked text is 'my link text'. When someone clicks this link, their browser will open the SharePoint document library in the SharePoint web interface:

{sp-link:documents}my link text{sp-link}

Here is another example, where the parameter name 'listName' is explicitly specified. The results are the same as the previous example:

{sp-link:listName=documents}my link text{sp-link}

In the following example, we link to a specific document 'checklist.docx' within the library:

{sp-link:documents/checklist.docx}my link text{sp-link}

Specifying the full path to your list

You must give the full path to the list (or library). In the above example, we have assumed that the list is located at the root (top-level) SharePoint site. However, if the list is in a SharePoint site called 'mySubSite' that is a child of the root site collection, you might specify the following:

{sp-link:/SiteDirectory/mySubSite/documents/checklist.docx}my link text{sp-link}

Linking to a document folder

To link to a folder 'my folder' within a document library, add a double forward slash(//):

{sp-link:documents//my folder}my link text{sp-link}

Office Integration

If you are using Microsoft Office integrated with SharePoint, the {sp-link} macro will make use of this integration. When someone clicks on the link created by the macro, it integrates with MS Office in the same way as SharePoint. You can check documents in and out of SharePoint and edit the document from within the Office application.

Requirements for the Office integration to work:

Your Confluence site or space must be using the SharePoint Decorators theme. See the instructions on configuring Confluence to use the SharePoint Decorators theme. If you are not using the theme, the link will still work but you will not be able to edit the document or check it in or out.
You must be using Internet Explorer as the browser when accessing the Confluence page.

Diagram: Office integration with the SharePoint Link macro

Examples of List Types

Below are some examples of the list types supported by the SharePoint Link macro.

Document Libraries

See the examples given above.

Links

Linking to a list of links:

{sp-link:lists/sample links}my link text{sp-link}

Calendars

Linking to a calendar:

{sp-link:lists/sample calendar}my link text{sp-link}

Tasks

Linking to a list of tasks:

{sp-link:lists/sample tasks}my link text{sp-link}

Issues

Linking to a list of SharePoint issues:

{sp-link:lists/sample issues}my link text{sp-link}

Discussions

Linking to a list of SharePoint discussions:

{sp-link:lists/sample discussions}my link text{sp-link}

Custom Lists

Linking to a custom SharePoint list:

{sp-link:lists/my custom list}my link text{sp-link}

Child pages