Using the SharePoint Connector for Confluence

The Confluence Page Web Part

The Confluence Tree Web Part

Using the {sp-list} macro

(Please note this documentation has been updated for version 1.0.4 of the plugin. The 'SharePoint Site Alias' notation has been added. If you have an earlier version of the plugin please upgrade if you'd like to reference multiple SharePoint Sites.)

The {sp-list} macro can display the contents of most lists in SharePoint.

Short Form

This form of the {sp-list} macro has predefined columns allowing for a shorthand notation.

{sp-list:<SharePoint Site alias>:<name of the list>|<list type>}

If you're referencing the SharePoint Site Server selected as the 'default' on the SharePoint Admin settings you can leave out the 'SharePoint Site alias'.

{sp-list:<name of the list>|<list type>}

• listName: is the name of the list in SharePoint
• list types currently supported:
  • doc, docs, document
  • link
  • cal, calendar
  • task, tasks
  • issue, issues
  • discussion, discussions

Examples shown below.

Full Syntax

This should all be on one line.

{sp-list:<SharePoint Site alias>:listName=<name of the list>|
columns=<sharepoint column name mandatory>,<column alias optional>,<column type optional>;
<sp col name>,<alias>,<type>|
debug=<true\|false>}

• listName: is the name of the list in SharePoint
• colums: defines the columns of list.
  • (Using 'view' as a column name will create a link back to the original SharePoint list).
• debug: when set to true will send the SharePoint SOAP response to the html source of the page. You can inspect by doing a 'view source' on the page.

List Name and path:

Currently the full path to the list must be written. For instance a document list in the root site could be embedded within a Confluence page with the following notation:

{sp-list:my site:my list|doc}

or if 'my site' is the default 'SharePoint Site'

{sp-list:my list|doc}

However if that list were in a SharePoint site under the root 'site collection' you might write.

{sp-list:sub site/my list|doc}

Displaying the contents of a document folder

The syntax is to add a // to retrieve a folder's content.

{sp-list:document-library//folder|doc}

(this syntax to display a document folder's contents is only supported in version 1.0.6 and higher of the Java plugin. The version of the SharePoint web parts you're using doesn't matter.)

Examples

Following are examples of the short hand notation, the long hand notation showing the same list and a screenshot of the output.

doc, docs, document

{sp-list:test doc library|doc}

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

link

{sp-list:sample links|link}

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

cal, calendar

{sp-list:Sample Calendar|cal}

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

task, tasks

{sp-list:Sample Tasks|task}

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

issue, issues

{sp-list:sample issues|issue}

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

discussion, discussions

{sp-list:sample discussion|discussion}

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

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 which the SharePoint service is returning in the HTML page but it is commented out. To see it you can right click on the web page and select 'View Source'.

You can the add additional columns to your macro if you wish to display additional data. As you'll see the macro trims off the prepended 'ows_' characters from the field name.

• In the case of the Confluence Pages Tree View web part it allows another web part to provide it the space key so that it can display the hierarchy of pages for the provided space.
• In the case of the Confluence Page web part it allows another web part to provide it the page ID so that id can display the Confluence page.

There are numerous scenarios for connecting web parts. A simple example is to use a List web part that contains space key and/or page ID information that can be provided to the SharePoint Connector for Confluence web parts. An example of this is shown below. The user simply clicks on the radio button to choose an item in the list and the corresponding space key and page ID are provided to the web parts below the list.

Screenshot: Web Part Connections

To reproduce the above sceanrio, do the following:

• Create a list that has a space key and/or page ID field.
• Create a web part page, go into edit mode on the page, and add the following to the web part page:
  • The List web part for your list
  • The Confluence Page web part
  • The Confluence Space Pages Tree View web part
• Edit the connection of the the Confluence Space Pages Tree View web part and set its provider to be the appropriate field from the list as shown below. You must be in edit mode on the page to make a web part connection.

Screenshot: Making a connection

Screenshot: Configuring the connection

There are many other scenarios for connections. Some other out of the box web parts that specialize in connections are the Filter Web Parts that come with the Enterprise version of MOSS. Each of these filter web parts allows you to configure it to obtain the space key or page ID from different sources and provide one of them to the SharePoint Connector for Confluence web parts. Here are some of the filter web parts in MOSS Enterprise.

• Business Data Catalog Filter - could provide a space key or page ID taken from a database or web service
• Choice Filter - can provide a hard-coded choice of space keys from which the user can choose
• Page Field Filter - looks at fields stored with the curren web part page document library item (in a Pages document library, for example) to provide their values
• Query String Filter - can provide values from the query string
• SQL Server 2005 Analysis Services Filter - can provide values from SSAS
• Text Filter - allows the user to type in a value that can be provided

From a technical standpoint, the SharePoint Connector for Confluence web parts consume the IWebPartField interface. This is one of the interfaces provided by the List web parts as well as the Filter web parts. You can create your own web part and have it provide data through this interface as well.

Troubleshooting the Plugin

The following help is available for troubleshooting the SharePoint Plugin:

• SharePoint Plugin configuration troubleshooting
• Diagnostics

Troubleshooting the SharePoint Features

The following methods are available for troubleshooting the SharePoint Features:

• Tracing the SharePoint Feature
• Troubleshooting SharePoint Search
• Broken Images in the Confluence Page Web Part
• Diagnostics