Using the sp-list Macro (v 1.1)

Owned by Almuth Boehme [Communardo]
Aug 18, 2016
5 min read

You can use the SharePoint List macro {sp-list} to display a SharePoint list on a Confluence wiki page. The macro can display most SharePoint list types.

Screenshot: The SharePoint List macro in Confluence



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 List macro into a page using the Macro Browser,

  1. Go to the Confluence page or blog post where you want to display the SharePoint list.
  2. Click the 'Edit' button. The page or blog post opens in edit mode.
  3. Click the Macro Browser icon on the toolbar.
  4. The macro browser window opens. Find the 'SharePoint List' 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.
  5. Click the macro to access its parameters and preview the macro output.
  6. Enter the macro parameters. See the parameter descriptions below.
  7. If you would like to preview your changes, click 'Refresh'.
  8. Click 'Insert' to add the macro to the page.

Usage with the Wiki Markup Editor

Basic Form

Unable to render {include} The included page could not be found.

Full Form

Make sure that you enter the entire text on a single line without any line breaks.

{sp-list:SHAREPOINT SITE ALIAS:listName=LIST NAME|columns=COLUMN 1 NAME,COLUMN 1 ALIAS,COLUMN 1 TYPE;COLUMN 2 NAME,COLUMN 2 ALIAS,COLUMN 2 TYPE|debug=TRUE}

Parameters

Unable to render {include} The included page could not be found.
Separating Multiple Parameters

In wiki markup, the parameters are separated by a pipe character (|). The SharePoint List macro has a slightly more complex format than other Confluence macros. For each parameter, you can enter multiple values separated by a comma (,) or a semi-colon (;). We give a detailed description in the table below.

Parameter

Default

Description

listname
(SharePoint site alias:listName)

No default

The first parameter can contain either just the name of the SharePoint list ('listName') or the SharePoint site alias and the list name, separated by a colon (:). The text 'listName' is optional.

The following example has two parameters. The first parameter contains just the list name 'documents'. (The second parameter is the list type, as described below, and is not relevant here.) For now, please look at just the first parameter before the pipe character (|):

{sp-list:documents|document}

In the next example, the first parameter contains an alias 'mySharePoint' and the list name 'documents':

{sp-list:mySharePoint:documents|document}

Here is another example with alias and list name, where the parameter name 'listName' is explicitly specified:

{sp-list:mySharePoint:listName=documents|document}


The SharePoint site alias is the nickname of the SharePoint server as specified in the SharePoint Admin settings. See the Confluence SharePoint plugin configuration guide. Note that this value is case sensitive – use the same capital and lower-case letters as in the plugin configuration screen.

The listName is the name of the list in SharePoint. This value is not case sensitive.

Specifying the full path to your list

You must give the full path to the list. 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-list:/SiteDirectory/mySubSite/documents|document}
Displaying the contents of a document folder

To display the contents of a folder 'my folder' within a document library, add a double forward slash(//):

{sp-list:/SiteDirectory/mySubSite/documents//my folder|document}

(Unnamed parameter: List type)

No default

Use this parameter to specify the type of the list in SharePoint. If you do not specify the columns (see below), then you must specify the list type. If you do not specify the columns, Confluence will display default columns for the given list type. The macro supports the following list types:

  • doc, docs, document
  • link
  • cal, calendar
  • task, tasks
  • issue, issues
  • discussion, discussions

    See the examples below.

columns
(columns)

If the 'list type' parameter is present and there is no 'columns' parameter, then SharePoint will display default columns for the given list type.

Use this parameter to specify the columns of the SharePoint list that will be displayed on the Confluence page. If you do not specify the columns, Confluence will display default columns for the given list type. If you specify both the list type and the columns, Confluence will display the specified columns instead of the default columns.
(info) Use 'view' as a column name to create a link to the original SharePoint list.

You can enter one or more columns, separated by a semi-colon (;). For each column, you can specify the column name, alias and type, separated by a comma (,). The format is:

columns=COLUMN 1 NAME,COLUMN 1 ALIAS,COLUMN 1 TYPE;COLUMN 2 NAME,COLUMN 2 ALIAS,COLUMN 2 TYPE

For example:

{sp-list:documents|columns=BaseName,Document Name,doc;FileSizeDisplay,File Size,fileSize;Modified,,date;Author,,author;view}


The column name is a unique SharePoint 'field ID' for the column. Please refer to Frode's awesome list of Sharepoint Column Field IDs. For example, to find the field ID for the column containing the file size, go to Frode's page for F to P. As shown on the page, the field ID is FileSizeDisplay.

Alternatively, you can use the 'debug' parameter to obtain a list of SharePoint field IDs. See more about the debug option below.

The column alias will be displayed as the column header on the Confluence wiki page. You can enter any value you like here.

The column type determines how the macro will format the value when displaying it on the Confluence page. The following values are supported:

  • fileSize – Formats the column value as a file size.
  • author – Formats the column value as a link to the user's profile on SharePoint.
  • date – Formats the column value as a date in the form "MM/dd/yyyy" (ie. the "American" format).
  • dateTime – Formats the column value as a date and time in the form "MM/dd/yyyy hh:mm aa".
  • url – Formats the column value as a hyperlink.
  • boolean – Displays a value of 'yes' or 'no'.
  • percent – Formats the column value as a percentage.
  • doc – Formats the column value as a link to a document in the SharePoint list.

debug

False

Set this parameter to 'true' if you want to send the SharePoint SOAP response to the HTML source of the page. You can see the result by viewing the source of the page. See more below.

Examples of List Types

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

Document Libraries

List types: doc, docs, document

Using the default columns:

{sp-list:test doc library|doc}

Specifying the columns:

{sp-list:test doc library|columns=BaseName,Document Name,doc;FileSizeDisplay,File Size,fileSize;Modified,,date;Author,,author;view}

Output:

List type: link

Using the default columns:

{sp-list:sample links|link}

Specifying the columns:

{sp-list:sample links|columns=URL,,url;Comments}

Output:

Calendars

List types: cal, calendar

Using the default columns:

{sp-list:Sample Calendar|cal}

Specifying the columns:

{sp-list:Sample Calendar|columns=Title;Location;EventDate,Start Time,date;EndDate,End Time,date;fAllDayEvent,All Day Event,boolean}

Output:

Tasks

List types: task, tasks

Using the default columns:

{sp-list:Sample Tasks|task}

Specifying the columns:

{sp-list:Sample Tasks|columns=Title;AssignedTo,,author;Status;Priority;DueDate;PercentComplete,Percent Complete,percent}

Output:

Issues

List types: issue, issues

Using the default columns:

{sp-list:sample issues|issue}

Specifying the columns:

{sp-list:sample issues|columns=ID,Issue ID;Title;AssignedTo,,author;Status;Priority;DueDate,Due Date,date}

Output:

Discussions

List types: discussion, discussions

Using the default columns:

{sp-list:sample discussion|discussion}

Specifying the columns:

{sp-list:sample discussion|columns=Title;Author,,author;ItemChildCount,Replies;DiscussionLastUpdated,Last Updated,date}

Output:

Custom Lists

List types: Not applicable

You can use the SharePoint List macro to display custom lists, provided that you specify the columns to be displayed.

Specifying the columns:

{sp-list:My Custom List|columns=Title;ID;Modified,,date;Author,,author;view}

Output:

The Debug Option

You can add a debug parameter to your macro as follows:

{sp-list:Sample Tasks|task|debug=true}

This will cause the macro to write out the XML for the list that the SharePoint service returns. The XML is included in the HTML page, but is commented out. To see it, right click on the web page and select 'View Source'. The XML will appear as part of the source, immediately after the following line:

<!-- starting xml output

The XML contains all the available SharePoint field IDs. This is one way of finding the values for the macro column names (see above). Note that you should strip off off the prefix 'ows_' from the field name before using it as a the macro parameter. Some field names include two underscores after 'ows' instead of just one. In that case, you should strip off only one underscore.

For example:

Field ID shown in XML

Column Name to use in Macro

ows_ServerUrl

ServerUrl

ows__EditMenuTableStart

_EditMenuTableStart

RELATED TOPICS

Working with Macros
SharePoint Connector User's Guide