The Latest Enhancements in Atrium 2.5

Mike Potter, Software Architect
#Atrium | Posted

Atrium Team Work Image

 

In Atrium v2.50 we have added support for exporting and importing Blueprints.  This allows you to easily share your Blueprints across different sites and can even be used for limited content sharing.

 What is a Blueprint?

 Atrium allows you to create complex structures of Spaces, Sub-spaces, and Sections to represent  your Information Architecture.  For example, a “Project” space might contain Sections for Tasks, Discussions, Calendar, and Files.  Once you customize your Project landing page to show lists of recent tasks, events, discussions, etc, you don’t want to repeat that work for each new project. Using the “Save Space as Blueprint” you can create a new custom space-type that points to your space template.  Your new blueprint will appear in the “New Space” and “New Subspace” drop-down menus and will create a complete clone of your original template. This clone will contain all of the Sections, default content, colors, page layouts, menus, and other configuration of the original template space that was used to create the Blueprint.Blueprints allow you to duplicate pre-configured spaces used for various use cases.  You might have Blueprints for a “Project” space, an “Office”, a “Region”, a “Knowledge Base”, etc.  This makes it very easy to create new content once you have defined these initial templates.

Exporting Blueprints

After spending a lot of effort to create your various Space Blueprints, how can you reuse them on other Atrium sites?  The problem is that the template Spaces, Sections, etc are *content*.  A Space or Section is a Drupal “node” and you cannot easily share node content between sites because nodes do not have any unique identifier.  Nodes in Drupal use sequential “id” numbers.  So on your original Site A, your Blueprint might point to node “1”, but on your new Site B, you might already have a different node “1”.To solve this problem, we created a new Atrium App called “Open Atrium Export” (oa_export). The job of this App is to export your Blueprint nodes in a format that can be imported on a different site. When the Blueprint nodes are imported, new Drupal nodes are created and the imported Blueprint is updated to point to these new node id values.

To export a Blueprint, simply visit the Drupal Taxonomy page for the Space Blueprint vocabulary. You can find this in your Drupal Admin -> Structure -> Taxonomy area. In the list of Space Blueprint terms, you will see an “export” and “download” link in the right-most “operations” column.

The “download” link allows you to export the Blueprint into a single “tar.gz” archive file. You can download this file to your local computer and then transfer it to the server you want to import.

The “export” link will actually create a new custom Drupal module and will store the Blueprint data within that module. You can then add this custom module to your other site code repository and when the module is installed on your remote server it will create the Blueprint content.

You can also export a Blueprint to an existing module or even create a new module.  All Blueprint data is stored within an oa_export subdirectory with an entities.json file that contains all of the content data. Atrium will automatically create the hooks in your *.install file to import the Blueprint when the module is enabled, or update hooks are triggered, but you can also put other custom logic into your module. In fact, your module might also contain “Features” export for configuration that might be needed by your Blueprint.

Content vs Configuration

To fully understand how Blueprint exports work, it’s useful to have a good understanding of the difference between “Content” and “Configuration” in Drupal. Content are your Spaces, Sections, Teams, Groups, Discussion posts, Events, Tasks, and other “nodes” within Drupal. Comments, paragraphs, page layout, taxonomy terms, menu items, files, and users are also “content”. Everything within the space except users will be exported into a Blueprint.“Configuration” are things like your content-types, fields, views, panelizer layouts (space and section templates), variables, and other site-wide settings. Configuration items can be saved to custom module code using the “Features” module. They define the structure of the content on your site.For example, when you create a Discussion Post, the content-type and fields used to define the post are “configuration”, but the actual content of the post itself is “content”.Some data, such as permissions, live in a gray area between “content” and “configuration”. You can export permissions using Features, but typically they become changed (overridden) on another site. Atrium will actually export your space permissions as part of the Blueprint content because you could have custom permissions for each space.

Importing your Blueprints

If you chose to export your Blueprint as an archive file visit the Space Blueprint taxonomy page and click the button - “Import Blueprint”.  It will prompt you for the “tar.gz” archive file that you previously downloaded.  If you exported the Blueprint as a new  module, add that module to Site B and visit the Drupal Modules page and enable the module. If you updated an existing module and it exists on both Site A and Site B, update the module on Site B with the updated module from Site A and run database updates. You can do this by visiting ‘/update.php’ in your browser.Any “node” content contained in the Blueprint will be created as new content.  Any taxonomy terms used in the Blueprint will re-use any existing taxonomy term with the same name on the current site.

For example, when you import a Space or Section node, new nodes for that Space and Section will be created. But when you import the “type” of section (the Section Type taxonomy term), it will search your existing site for a matching term. If a matching term isn’t found, then a new taxonomy term will be created. Since your new site already has section types like “discussion” and “calendar” you wouldn’t want those duplicated.

After importing the Blueprint, you should see the Blueprint listed in the “Create Space” and “Create Subspace” dropdown menus.  Now you can create new spaces based on these Blueprint templates just like you did on the original site!

Keep in mind that your new site still needs to have the “configuration” from the old site, typically via Features modules. For example, if you export a Section based on the “Calendar Section”, Atrium assumes the “Calendar Section” configuration already exists on the new site. If you have defined your own custom Section templates, or your own content-types, fields, or views, be sure those are installed on your new site before you attempt to import the Blueprint content.

Migrating Content

Since the Blueprint Export and Import will transfer “nodes” between your sites, you might be tempted to use this to migrate other content of your site.For example, imagine that you have an existing Knowledge Base space that contains many different wiki documents and various external files (pdf, doc, etc). If you use the “Create Blueprint from this Space” option and then export this new Blueprint, then you could import it on a different site and you’ll end up with a copy of the entire Knowledge Base. Yes, Atrium will even transfer the external Files!Wonderful! Now you can transfer the content of your Atrium site to another site. But be careful; there are several disadvantages to using Blueprint Export to transfer general content:

  • All content imported by a Blueprint will be owned by the site admin account.  Original authorship will be lost.
  • All content will be new and will have a timestamp of your import.  You lose the original creation/modification times of the content.
  • Only the current revision of content is exported/imported.  You lose the revision history of the nodes.
  • New content is always created, so if you already have the Blueprint imported and you import it a second time, you’ll end up with duplicate content.

In general, it is probably wiser to migrate your content via normal methods, such as using the Migrate module which is specifically designed for content migration.We might use the Migrate module for the Blueprint Export/Import in the future. But exporting some parts of the content, such as the custom panelizer page layout and widgets on a space, or the paragraphs on space, can be tricky to handle with Migrate, so we wrote our own export/import code instead.

Conclusion

Blueprints are very powerful and unique features of Atrium that allow you to quickly build the Information Architecture of your site then use them to easily create new content on your site.  Being able to export and import these Blueprints make them great for re-using Spaces and their dependent entities across multiple sites.  In the future you’ll even see Atrium itself offer some pre-built Blueprints for various use-cases such as Project management.  Just be careful if you try to use this functionality for general content migration:  “with great power comes great responsibility.”Register for our upcoming Atrium webinar and learn more about the Blueprint Export feature in Atrium 2.5!Let's collaborate Atrium Image

Mike Potter

Software Architect