Confluence and the power of Excerpt and MultiExcerpt

[#1]

Information Radiation and the power of a little marketplace macro: MultiExcerpt

One of the key features of Confluence is the radiation of information or how you can easily share information across the environment, avoid duplication and copy-paste, and reduce the steps to update information. There are multiple ways of doing that, it could be by embedding pages into other pages or using macros like Excerpt, or if you can add marketplace apps, you can also use MutliExcerpt.

In the article The Purpose of the Atlassian Marketplace, I explained why it is essential to keep an eye on the out-of-the-box functionalities and the Atlassian Marketplace to maximize our platform's usage. In this particular case, I will explore the macro Excerpt's functionalities included with Confluence, its limitations, and the big brother offered by the Marketplace that will go beyond basic features. I think that MultiExcerpt macro should be part of the product, but the Atlassian Ecosystem exists to provide opportunities to entrepreneurs and solutions to the users. When you use styles to create a document, you can change how the whole document looks with just a few clicks.

Let’s explore the business need first.

Let's consider that you have products and a confluence page for each one to host all the product-related information. For this example, I will use two products, a can of beans and a can of sardines. (in your case, think about your own "element," software modules, apps, events, team members, projects, etc.).

Basic approach

In a plain confluence page, we can host all the information related to the product, including images of the packaging, logo, bar code, etc. It will be a rigid block of data, and, if we need to share the information, we will have to do it as one artifact. Confluence provides a mechanism for that by just sharing the link to the page or embedding it into another page or blog post.

For a single page, we probably achieve our goal, but the whole purpose of this article is to generate content that we can reuse and share. Let's explore some scenarios.

Scenarios

“What if... #1”, → (Excerpt)

What if we just want to share a piece of that page?. Well, the solution is easy, we can use the macro Excerpt, that will allow us to specify a piece of content that could be used with other macros (like include excerpt or reports by labels). So far so good! We added a little flexibility to our rigid block of information.

“What if... #2”, → (MultiExcerpt)

What if we need a couple or more pieces of information from that page?. Well, here is the bad news, out of the box we can have just one excerpt macro per page, sorry about it!.

• Workaround 1: Split the content into multiple children pages and embed them into the main page
• Workaround 2: invite the marketplace big brother “MultiExcerpt” to our family reunion and have some fun minimizing the number of pages and facilitating the reuse of information.

Excerpt and MultiExcerpt benefits

Having the content as one big block of information will block the way you radiate information. Of course, using child pages could help, but you need to be careful about how many pieces you will use to build additional pages, it could seriously affect your performance.

The main benefit of using Excerpt or MultiExcerpt is that you need to worry about just one place to host and maintain the information.

The Excerpt Macro (out of the box)

We can address our “What if... #1” business needs with the Excerpt Macro (full documentation is here).

It is easy to use (just keep in mind that it is just one per page). Add the macro and then place the content inside of it. It can be any type of content, including images. In the example below I am placing inside the macro the label picture.

This page is the "container" of the information that we will reuse in other pages.

To use that information on a different page use the macro: Excerpt Include  and the content will be populated. Any change on the host page will be immediately reflected in all the pages using the information. Good improvement and reduction of data duplication.

Excerpt macro can be also used with other macros as parameters. (In this case please keep consistency on the type of content placed inside the macro). See below few examples of re-purposing content by using Excerpt.

As you can see above, we are just showing the content inside the macro Excerpt, and we are not using the entire page content. A little bit of flexibility added to our information sharing experience.

Why we need the big brother MutliExcerpt?

We can not address our “What if... #2” business case the macro Excerpt, but it could be satisfied by splitting the content in a certain number of children pages. (probably too many if you need little pieces of information).

Going back to the products that we are using as an example, you can see on the picture of the can label or sardine can packaging that we have one image that could represent the full product. It is probably ok for our purpose, but (as in many products) what happens if we want to use just pieces of it based on specific needs.

The pieces of information in the product packaging like

• Label
• Product Name
• Calories
• Expiration Date
• Brand
• Content
• Factory
• Bar Code
• Ingredients

How can we use just some pieces of information? 

The marketplace app that includes the macro MultiExcerpt and Include MultiExcerpt address this particular need.

Step 1: Prepare the Product Page (information host)

(Note: other macros use just the regular Excerpt, so you will probably need to use that one for the essential piece of information and then use MultiExcerpt for additional data)

The recommendation is always to use the Excerpt Macro first and then add other information blocks using MultiExcerpt. In our example, I will keep the label inside the Excerpt macro and the rest on MultiExcerpt blocks. The page containing the macros and information is the only one that we will need to update, all the pages consuming the data will update the content in real-time.

In the page structure below, you will see three blocks of information

1.  Excerpt: containing the label - You can use only this information by adding the macro: Excerpt Include in your new page
2. MultiExcerpt: having the table and with the name: Details - You can use only this information by adding the macro: MultiExcerpt Include in your new page and providing the host page information as parameters
3. MultiExcerpt: containing the table and with the name: Ingredients - You can use only this information by adding the macro: MultiExcerpt Include in your new page and providing the host page information as parameters

Page with the Excerpt macro and MultiExcerpt macros.

Using the information from MultiExcerpt

The new page will show the information that is inside the "Details" MultiExcerpt macro.

We will use now the content that is inside the Ingredients MultiExcerpt 

Can we still use the Page Include macro?

Yes, Our final page will look as the original one, so there is no difference there for the end-user,  the key benefits are how we can radiate that information in other areas of our Confluence instance and reduce maintenance time.

Below I am using the macro Include Page selecting Page 3 that contains both Excerpt and MultiExcerpt macros.

Bonus Tip: Empowering the usage of the content by combining the macros with the "Page Properties" macro

(Note: this approach apply Nested Macros that is not available in Confluence Cloud)

Both, Excerpt and MultiExcerpt macros could be used within the Page Properties macro and then use the information with the "Page Properties Report". In order to do that we will need a couple of tweaks to our original pages:

1. adding a label (product) and

2. adding the Page Properties macro that includes the information as a table. 

To demonstrate this Bonus Tip we will have two pages with the same structure, one for Beans and the other one for Sardines.

Page Sardines

Page Beans with label "product"

Using "Page Properties Report" macro

Time to practice

The MultiExcerpt macro is developed by Artemis Software and it is available in the marketplace. The oldest version published is from 2011 but I remember using it since 2008. Keep in mind that the main purpose of creating content in Confluence is to share it and repurpose it. The article is based in the server version but the macro is available for Cloud and Data Center.

Excerpt macro is included with Confluence and it has the limitation that you can use just one per page. Excerpt is powerful as you can use it with other macros like Report by Label. I hope you can use it and enjoy the experience. Have Fun!

[Matt Doar]

Very clear article, thanks!

[Fabian A. Lopez (Community Leader - Argentina, Florida, California)]

Thanks @Matt Doar 

[Len Jaffe]

Please change this sentence "In the example below I am placing inside the macro the label picture." to

"In the example below I am placing the label picture inside the macro."