Blog Archives

Want an XML schema viewer in Confluence wiki?

You got it. :) Avisi have developed two nifty macros to display an XML schema (XSD) in tabular and graphic format on a Confluence page. The XSD Viewer is a new add-on for Confluence wiki, and the Avisi developers are keen for input from technical writers and others interested in XML schemas.

I’ve been playing around with the add-on, so I’d love to show you a couple of examples and tell you how to get it working for yourself. I’ve also chatted with Yanne from Avisi, who says that he and his team would love to have your feedback.

Example 1:  A purchase order schema

I’ve grabbed the sample schema for a purchase order from MSDN: http://msdn.microsoft.com/en-us/library/ms256129.aspx. I’ve instructed the XSD viewer to start with the purchaseOrder element, and show a depth of 2 levels.

Want an XML schema viewer in Confluence?

Example 2: Graham Hannington’s schema for the Confluence storage format

Hehe, if you put Confluence and XSD in the same blog post, then ‘twould be remiss not to include Graham’s XML schema for the Confluence storage format. :D

The XSD Viewer is using confluence.xsd, starting with the image element.

Want an XML schema viewer for Confluence?

One point of interest here is that the confluence.xsd file references two other schema files: confluence-ri.xsd and confluence-xhtml.xsd. All I had to do to make this work, was to attach all three XSD files to the page. This screenshot shows the attachments on the above page:

Want an XML schema viewer in Confluence?

Hiccups

A couple of times, the XSD Viewer has declined to show any rows in the table. I’m not sure why this occurs. If it happens to you too, it’s worth letting the Avisi team know.

My environment

I’m using Confluence 5.0.1, with version 1.1.1 of the XSD Viewer. I’m running Confluence on my Windows 7 laptop, and I’m using Chrome to view the wiki pages.

How to get your own XSD viewer

To make this happen, you need to do the following:

  1. Download and install Confluence, if you don’t already have it. You can try it for free for 30 days. See the Confluence download page.
  2. Download the XSD Viewer add-on and install it into Confluence. The add-on is also available for free for 30 days. See the XSD Viewer page on the Atlassian Marketplace.
  3. Create a page in Confluence.
  4. Attach your XSD file to the Confluence page, just as you would attach a screenshot or other file. See the documentation on adding attachments.
  5. Edit the page.
  6. Add the “XSD Image” and/or the “XSD Table” macros to the page. See the documentation for the XSD Viewer.
  7. Save the page.

Resources

Useful links:

Feedback so far

I’ve given Yanne at Avisi some feedback already:

  • At first the error messages were a bit too generic to be useful. Avisi have already followed up on this in the latest version of the add-on, which gives more specific error messages. Great!
  • Currently the macro autocomplete in Confluence is triggered by “XSD”. Suggestion: Add “schema” and “XML” to the list of triggers.
  • Add the option to add a border and other styling to the image.

The Avisi team like the latter two suggestions, and are waiting for more feedback before implementing them. Would you be interested in an XSD viewer in Confluence, and what requirements would you have for it?

How to search for macros and macro parameters in Confluence 4

Do you need to find all pages that use a given macro with given parameters and parameter values? For example, do you need to find all pages that use the Excerpt Include macro to include content from a given page? Or all pages that display the children of another page? Or all pages that display a given PDF file?

In a standard Confluence 4 installation, that is not possible because the macro parameters are not indexed. There is a new plugin available that makes the search possible: the Confluence Macro Indexer plugin.

A quick note before we start

Using the standard Confluence functionality, you can already search for occurrences of a given macro (but not its parameters). Enter the following in the Confluence search box, assuming that your macro name is “x”:

macroName: x*

You don’t need a plugin to use the above syntax. For details, see my previous post: How to search Confluence for usage of a macro

What’s new

The Confluence Macro Indexer plugin enhances the Confluence search, so that you can search for specific macros, macro parameters and/or parameter values. With the plugin installed, your Confluence site will allow a new search field name that you can enter into the Confluence search box, followed by a colon, like this:

wikiMarkup:

The plugin is available for Confluence 4.0 and later. I’m using Confluence 4.3.

How to use the macro search

Before you can use the macro search, you or your administrator must install the plugin onto your Confluence site. Installation structions are at the end of this post.

To use the search:

  1. Enter 'wikiMarkup:' followed by the macro name and/or parameter, into the Confluence search box at top right of the Confluence screen, or on the standard Confluence search screen.
    For example: To find all occurrences of the Include macro that include a page called ‘Introduction to chocolate':

    wikiMarkup:"include:Introduction to chocolate"

    There are more examples below.

  2. Press Enter or choose Search. The search results will appear as usual.

Notes:

  • After installing the plugin (see instructions below), you will need to reindex Confluence to ensure that all macros on existing pages are added to the index. See the guide to administering the Confluence content index.
  • The field name is case sensitive. You must enter ‘wikiMarkup:‘, not ‘wikimarkup:‘ or any other combination of case.
  • The macro names, parameter names and parameter values are not case sensitive.
  • You will need to include double quotation marks around the text after the field name, if the text includes special characters such as a colon. For example, enter the following code to find all occurrences of the Include macro that include a page called ‘Introduction':
    wikiMarkup:"include:Introduction"
  • To use the search, you need to know the wiki markup for the macro name, the parameter names, and the accepted parameter values. The Confluence 4.x documentation contains such information for some of the macros. See https://confluence.atlassian.com/display/DOC/Confluence+Wiki+Markup+for+Macros. For the other macros, please refer to the Confluence 3.5 documentation: http://confluence.atlassian.com/display/CONF35/Working+with+Macros.
  • The plugin enhances the search only for macros and macro parameters – not for URLs in links or other such items.
  • The works for user macros too.

Examples

Find all pages that use a given macro

To find all pages that use the Excerpt Include macro:

wikiMarkup:excerpt-include

It works with quotation marks too:

wikiMarkup:"excerpt-include"

Find all pages that include an excerpt from a given page

To find all occurrences of the Excerpt Include macro that include content from a page called ”Introduction to chocolate':

wikiMarkup:"excerpt-include:Introduction to chocolate"

Find all pages that include a given page

To find all occurrences of the Include macro that include a page called ‘Introduction to chocolate':

wikiMarkup:"include:Introduction to chocolate"

Note: In fact, the above search will find the occurrences of the Include macro as well as the Excerpt Include macro.

Find all pages that include any page with a name starting with a given string

To find all occurrences of the Include macro and the Excerpt Include macro that reference any page that has a name starting with ‘Introduction':

wikiMarkup:"include:Introduction"

Find all pages that display a given PDF file using the View PDF macro

To find all occurrences of the View PDF macro that display the file ‘ChocRecipe.PDF':

wikiMarkup:"viewpdf:name=chocrecipe.pdf"

Find all pages that display the children of a given page

To find all occurrences of the Children macro that display the children of a page called “Chocolate home”:

wikiMarkup:"children:page=chocolate home"

Find all occurrences of all macros referencing a specific parameter

You can find all macros that have a specific parameter and a specific value assigned to that parameter. For example: If there are two macros, MacroA and MacroB, that have the parameter "page=My page name", then your search will pick up all pages that contain either MacroA or MacroB.

This search query will pick up all Children macros, just like the previous example. It will also pick up any other macros that have the same “page” parameter.

wikiMarkup:"page=chocolate home"

Screenshots

Searching for all occurrences of the Include and Excerpt Include macros that include content from a page called ”Introduction to chocolate':

Searching for all occurrences of the View PDF macro that displays the file ‘ChocRecipe.PDF':

How does it work?

In order to understand how to use the enhanced search, it’s useful to know exactly what the plugin does.

The plugin converts the macro code from Confluence 4 storage format to Confluence 3 wiki markup, and then adds the result to the Confluence index, thus making it searchable.

Let’s take the Excerpt Include macro as an example. The plugin takes the following code:

<ac:macroac:name="excerpt-include"><ac:parameter ac:name="nopanel">true</ac:parameter><ac:default-parameter>Introduction to chocolate</ac:default-parameter></ac:macro>

and converts it to this:

{excerpt-include:Introduction to chocolate|nopanel=true}

It then adds the above text to the Confluence index.

How to install the plugin

You can install the plugin via the Confluence plugin manager, just like any other plugin.You need Confluence System Administrator permissions to do this.

If your Confluence site is open to the Internet:

  1. In Confluence, choose “Browse” > “Confluence Admin” > “Plugins”.
  2. Choose “Install Plugins”.
  3. Type “macro indexer” in the search box on the “Install Plugins” tab, and choose “Search”.
  4. Click the plugin name “Confluence Macro Indexer” to see the plugin details.
  5. Choose “Install”.
  6. When the plugin is successfully installed, rebuild the Confluence index to ensure that all macros on existing pages are added to the index. See the guide to administering the Confluence content index.

If your Confluence site cannot access the Internet:

  1. Download the plugin JAR from tha Atlassian Marketplace: https://marketplace.atlassian.com/plugins/com.atlassian.confluence.plugins.confluence-macro-indexer-plugin
  2. Save the JAR file somewhere on your local computer.
  3. In Confluence, choose “Browse” > “Confluence Admin” > “Plugins”.
  4. Choose “Install Plugins”.
  5. Choose “Upload Plugin”, browse to the saved JAR file, and upload it.
  6. When the plugin is successfully installed, rebuild the Confluence index to ensure that all macros on existing pages are added to the index. See the guide to administering the Confluence content index.

The Confluence Macro Indexer plugin installed

Version management gets serious with Confluence Scroll Versions plugin

The team at K15t Software have just announced the first production release of Scroll Versions, an exciting new plugin for Confluence wiki. Our technical writing team has been working with the K15t guys on specifying and testing Scroll Versions. We and K15t are delighted with the 1.0 release. What’s more, K15t have exciting plans for adding even more features to the plugin. These features are what technical writers dream of. ;)

This video, produced by K15t Software and narrated by Kelly McDaniel, gives an excellent overview of the plugin’s functionality.

Why I’m excited about Scroll Versions

For me, the selling point is version management. And I’m over the moon about the enhanced features planned for future release.

What’s new about the version management offered by Scroll Versions? The standard Confluence functionality (without any additional plugins) includes a good solution for version management of single pages, and of entire manuals:

  • At the page level: Every time someone updates a page, Confluence saves a new version of that page. You can see the page history, compare two versions to see what changed, and revert to a given version at any time.
  • For version management of a manual or a set of documents, we use spaces. For each major release of the product, we copy the contents of a documentation space to a new space and brand it for the new version of the software.

But it’s difficult to mark a set of documents for publishing in a batch. For example, you may want to publish a page of release notes and a couple of minor updates for a point release of the product. Or you may be developing a new subset of documentation, not related to a product release, and you want to publish all the pages at once. Or, of course, you’re working towards a major software release and need to bundle a batch of new pages, updates and deletions for publication on release date.

In an agile environment, you may need to have a number of versions – let’s call them “branches” – running at the same time, each for a different feature. And you need to publish those versions – or “merge those branches” – at fairly arbitrary time intervals.

This is what Scroll Versions can give us now. You can have a number of versions of your documentation in draft state. You can create and manage multiple versions of the documentation, all in one Confluence space, all at the same time. A version consists of a set of new and updated pages, and even page deletions.

When you’re ready, you can publish a given version of the documentation. The effect is that people who view the content of the space will see that version only.

The other versions, both past and future, remain available in the space. You can publish any version at any time. You can even go back to a previous version. You can publish your version to the current space or to a new space. The versions are incremental. For example, version 1.2 of your documentation will include all the updates from version 1.1. You can change these dependencies at any time, making version 1.2 dependent on version 1.1.9 instead of 1.1, for example.

A future release of Scroll Versions will add conditional publishing, as well as the ability to publish from one space to a different, already existing space, thus merging the new version with existing content in a different space.

This screenshot shows the Scroll Versions configured in my test documentation space. I have set up a few versions:

  • 1.0 – the original version of the documentation that existed when I installed Scroll Versions.
  • 1.0.1 – a bug-fix release, based on version 1.0. This is the currently-published version of the documentation. I used Scroll Versions to publish it.
  • 1.0.2 – an upcoming bug-fix release, based on version 1.0.1. This version is not yet published.
  • 1.1 – the next major release, based on version 1.0. See the nifty branching visualisation to the left of the version numbers!

I would probably change the dependent version of my 1.1 release a few days before publishing it. I would make it depend on the last bug-fix release, which may at that stage be 1.0.9, for example. By changing the dependency, I make sure that version 1.1 picks up all the changes made in versions 1.0 to 1.0.9.

Other goodies in this release

Using Scroll Versions, you can have more than one page with the same name in the same space. Yes, duplicate page names are now possible.

There’s also a new macro for enhanced content reuse. And you can add permanent identifiers to pages, which stay the same across multiple versions and different spaces – useful when you want to use the wiki  as an online help solution.

How to set up and use Scroll Versions

I’m using Confluence 4.2 and Scroll Versions 1.0.1.

Note: For the purposes of this post, the words “add-on” and “plugin” mean the same thing. The Atlassian Marketplace refers to “add-ons” and the Confluence user interface calls them “plugins”. The term “add-on” is broader than “plugin”, since an add-on can refer to other types of extensions. Scroll Versions is a plugin.

If you don’t already have Confluence, you can install an evaluation Confluence site and use it for 30 days free of charge. It’s quite easy to install Confluence on a laptop or desktop computer:

  1. Go to the Confluence download page.
  2. Download the installer for your operating system.
  3. Run the installer and follow the instructions it gives you.
    • Choose the default options for an evaluation installation.
    • When the installer has finished, it will open the Confluence setup wizard in your web browser. Follow the instructions to configure Confluence, again choosing the default options for an evaluation installation.
    • Choose to include the sample data. This will give you a wiki space full of content that you can play around with. It’s called the “Demonstration” space and has a space key of “ds”.
    • Generate an evaluation licence key as prompted, and paste it into the Confluence licence key text box.

To set up Scroll Versions on your Confluence site:

  1. Go to the Scroll Versions plugin page on the Atlassian Marketplace.
  2. Choose the big blue button that says “Free 30 Day Trial”.
  3. Follow the instructions as prompted, to do the following:
    • Generate a 30-day license for Scroll Versions.
    • Download the plugin (a JAR file).
    • Install the plugin via the Confluence administration screen.
    • Add your Scroll Versions licence key via the Confluence administration screen.

Now you have Scroll Versions on your site. The next step is to enable it in your documentation space:

  1. Go to a page in the space. If you’re using an evaluation site, you can use the Demonstration space at this URL: http://localhost:8090/display/ds
  2. Choose “Browse” > “Scroll Versions”.
  3. Follow the instructions as prompted, to do the following:
    • Activate version management in your space, and choose the version for the content currently in the space.
    • Define the groups of people who will be able to write version-controlled content (the “Authors”) and the people who will be able to configure the Scroll Versions behaviour in the space (the “Doc-Admins”). Hint: If you’re evaluating the plugin on a test site, it’s easiest just to assign the “confluence-users” group to both these roles. The “confluence-users” group consists of everyone who has permission to log in to your Confluence site.
    • Determine whether your space should allow duplicate page names.
    • Save your changes.

Your space is now configured to use Scroll Versions for version management. The next thing is to add a version or two, and start playing with them.

To add a new version of your documentation in your space:

  1. Go to a page in the space.
  2. Choose “Browse” > “Scroll Versions”. You will see that there are now two big green buttons, one called “Manage Versions” and one called “View Configuration”. The second button takes you back to the configuration steps that you’ve just done above. If you clicked it, come back again!
  3. Choose “Manage Versions”.
  4. Choose “Add Version”.
  5. Add the details for your new version. For example, it may be version 1.0.1, which is based on version 1.0.
  6. Add a couple more versions, just for something to play with.

When you go back to the pages in your space, you’ll see the Scroll Versions information panels at the top of each page. The version information panels and options are visible only to the people in the groups you specified as Scroll authors or doc-admins. Other viewers of the space will see just the wiki page, as usual.

Now that you have Scroll Versions set up, it’s a good time to watch that video again (at the top of this post) and then start playing with the product.

More reading, and feedback

This is K15t Software’s blog post announcing the release:  Announcing Scroll Versions – Concurrent Version Management for Atlassian Confluence.

The documentation is here: Scroll Versions Documentation.

The team at K15t Software are very keen to have our feedback. Happy wiki version management!

Yaayyy a Confluence doc sprint coming soon

We’re holding one of our famous choc fests, uh, doc sprints! This time we’re targeting the Confluence developer documentation. We plan to build some simple but lustworthy Confluence add-ons, and write them up so that other people can follow in our footsteps.

A doc sprint is an event where some seriously cool people spend time together, building plugins and other add-ons, and crafting tutorials around them. This one is hosted by Atlassian – makers of Confluence wiki, and where I work. The doc sprint is happening in Sydney, San Francisco, Amsterdam, and online for everywhere else.

Has anyone held a doc sprint in Amsterdam before, or are we the first? ;) A little bird told me there’s a divine chocolate shop just around the corner from the Atlassian office. The ideal venue for a doc sprint!

Event details

Date: Wednesday 22 August to Friday 24 August 2012 (3 days)

Location in Australia: The Atlassian Sydney office, 173-185 Sussex Street, Sydney, Australia

Location in the US: The Atlassian San Francisco office, 1098 Harrison Street, San Francisco, CA, 94103, USA

Location in Europe: The Atlassian Amsterdam office, Keizersgracht 311, 1016EE Amsterdam, Netherlands

Online: Want to join us remotely? If you can’t make it to Sydney, San Francisco or Amsterdam, or if you’d like to spend just a few hours rather than the whole two days, drop in on our daily webinar sessions, follow the buzz in our online chat room and subscribe to our email list. We’ll fill in the details nearer the date.

Sign up and tweet

Are you a plugin developer with a bent for writing, or a writer with a knack for plugin development? Add your name to the list of attendees. Make sure you tell us your chocolate middle name. Take heed: Your choice of name may have unexpected consequences.

And tweet #AtlassianDocSprint.

What will you get out of it ?

  • A designer, limited-edition, Atlassian doc sprint T-shirt. No-one else in your ‘hood will have one like it!
  • Eternal recognition as author. Your name will appear as author of the tutorial on the Atlassian documentation wiki.
  • Kudos from the Atlassian technical writers. We’ll write up our results on the Atlassian blog and you’ll be inducted into the Doc Sprint Hall of Fame.
  • Learn while you write. We’ll have some Atlassian developers on tap to help us over the sticky spots. Pair with a technical writer to get those words buzzing.
  • Chocolate. Indubitably, there will be chocolate in there somewhere.

Confluence tip – HTTP 500 or 504 error with Copy Space plugin

This tip is for people using the Copy Space plugin on Confluence wiki. If you’re copying a large space, you may see an HTTP 500 or HTTP 504 server error a few minutes after starting the space copy. Don’t panic. It’s likely that the copy process is still going on. Whatever you do, don’t close the browser tab or window until you know for sure.

It happens to me often, and it happened in a rather spectacular fashion earlier this week. I’m letting you know, in the hope that I can save you from a moment of panic. Or, as in my case this week, from a few hours of unnecessary frenzy.

About the HTTP 500 and HTTP 504 errors

When you get an HTTP 500 error, your browser window displays a message something like this:

  • 500 Internal Server Error
  • Internal Server Error
  • HTTP Error 500

The error message is a bit useless. It doesn’t give you much information, and it sounds very dire. Basically, it means that something has gone wrong and the server can’t give you more information. This is the error we get when using the Copy Space plugin on our production documentation wiki.

I’ve also seen an HTTP 504 error appearing in the same situation on a test server. It seems that the server configuration determines which error you get. HTTP 504 is a Gateway Timeout error. That’s a bit more helpful and a little less scary.

What to do if you get an HTTP 500 or 504 while copying a space

First, wait a while. It is most likely that the front end has timed out, but the copy process is still happening in the background. Do not close down your browser.

Open another browser window or tab, and try going to the address of your new space. The space will become available when the copy operation has finished. Keep trying.

How long should you wait? Ah, now there’s the rub. The copy operation can take anything from a few minutes to a few hours, depending on the size of your space. Until this week, I would have said 2 hours was the maximum time to wait. This week, one of our spaces took 5 hours to copy. I guess the answer is: It depends on your previous experience with copying spaces on your wiki.

When the waiting period has gone on too long, raise the alarm with your system administrators. Ask them to examine the logs to see what has happened, and to determine whether the process is still running.

If you have no joy there, start the copy process again.

What is the Copy Space plugin?

The Copy Space plugin is an add-on that you can install into your Confluence wiki. It gives you a way to copy the content of a space to a new space, with a new space key. One of the Confluence developers wrote this plugin for the Atlassian technical writers, and it’s available for everyone else to use too. It is not a supported plugin, but we use it all the time. It would be very difficult to do without it.

There’s a request for the Copy Space plugin to be supported and bundled with Confluence: CONF-14198. If you like, you can vote for and comment on the issue. If the plugin were supported and bundled, we could ask for better handling of long-running tasks. :)

Banksia flower

I love the colours of this Banksia flower I saw when walking in the Australian bush. The flower head is made up of hundred of tiny individual flowers. (Ref.) Perhaps 500, or even 504? ;)

Follow

Get every new post delivered to your Inbox.

Join 1,465 other followers

%d bloggers like this: