SYSTOPIA Extension Of The Month #2: CiviOffice

Közzétéve
2024-02-23 07:12
Written by
SYSTOPIA - member of the CiviCRM community - view blog guidelines

CiviCRM comes with useful building blocks known as extensions. Extensions do not only add new functionalities to the core, their modularity also allows for highly customizable setups. To use and integrate extensions effectively you have to know what they do. In this series, we share some of the extensions we built and maintain at SYSTOPIA – which are over 60 now (only those actively maintained). So get ready for at least 5 years of “extension of the month”! ;)

What is this extension about?

CiviOffice makes it possible to use .docx files as document templates in CiviCRM in lots of different workflows.

This solves problems users frequently have with document templates: The usual way to design documents in CiviCRM involves formatting with HTML and CSS. This is a skill not all users have, and even if they do, it makes for a painstakingly slow process to create and update documents. HTML and CSS were made for web design in the first place, while documents such as .docx or .pdf have different requirements such as standardized page dimensions and spreading content across multiple pages for printing.

Here’s what CiviOffice offers:

  • Input from .docx - a common file format that can be created by users of all skill levels with any word processing software
  • Compatibility with all CiviCRM tokens to use in document templates, including custom tokens
  • Output as .docx or .pdf for further processing
  • A document store to manage document templates across an organization
  • Live snippets to add dynamic content
  • Developer interfaces to enable integration with other extensions

Who is it for?

CiviOffice gives more autonomy to CiviCRM users in comms. No need to ask for a developer’s help, creating a nice looking series of documents including CiviCRM data and adjusting them to your needs is now as easy as creating a document in your favorite text software.

It’s also a versatile tool for all fans of workflow automation. You can use CiviOffice as a building block for all processes that need custom documents, such as donation receipts, event communication, application management and many more.

How do you use it?

While the usage of CiviOffice is pretty accessible, the initial set-up and configuration can be tricky. Please refer to the technical documentation for a more detailed report on how to install and configure the extension.

Managing document templates

Once the extension is configured, you can start creating your documents templates: To draft and design your .docx file, use any word processing software such as LibreOffice, OpenOffice or - if you must – even Microsoft Word.

You can use all CiviCRM tokens to integrate data in your document templates. A page listing the tokens available can be found at the new navigation link created by CiviOffice or /civicrm/civioffice/tokens. Smarty syntax is not (yet) implemented.

Upload your .docx files as private or shared document templates to the built -in local document store located at /civicrm/civioffice/document_upload.

Screenshot of CiviOffice navigation links and uploaded documents page
CiviOffice creates new navigation links for CiviOffice settings, uploading documents to the document store and a list of available tokens.

Creating Documents

To use these document templates your have several options:

  • Creating a document for a single contact
    The new option“Create CiviOffice document” in the actions menu of the contact overview allows you to pick a document template and the desired output file, as well as other settings such as creating an activity and add “live snippets”.
  • Creating several documents for multiple contacts
    From a contact search result, selecting the action “Create Documents (CiviOffice)” will take you to similar form with addition options to adjust the batch size. The result is a .zip archive containing the document for each contact.
  • Creating documents for contributions, memberships or participants
    From their respective search results, you can also create CiviOffice documents for other entities using the “Create Documents (CiviOffice)” action. Note that your CiviCRM tokens are context-dependent. For example, you can only use a token for the contribution amount when operating on contribution search result.

Live Snippets

CiviOffice provides a means to insert dynamic content when creating your document. The so-called "live snippets" offer a token-based approach to insert content that is neither static nor comes from CiviCRM data. This might be useful e.g. to insert a personal address into your standard letter. Go to your global CiviOffice settings and add one or more snippets. When creating documents, CiviOffice offers you one form field per live snippet to enter your dynamic content.

What is it good for?

CiviOffice is an open modular framework that can be integrated with many other extensions. On its own it can create documents with CiviCRM tokens. For example: a simple letter with a contact’s name and address or a Thank You note for a contribution. But it’s with its friends that CiviOffice can truly shine:

Together with the extension donation receipts you can use CiviOffice to add a personalized cover letter in your corporate design to your donation receipt - adding a little bit more flair in the same step.

Together with event messages, mail attachment and mailbatch, you can add CiviOffice documents to your event communication. This combination can be used for example to automatically sent a .pdf with an confirmation of participation to each participant after they have attended an event. A true timesaver on repetitive tasks when handling a ton of events!

Can I have Smarty...

No, sorry, that's one of the shortcomings it has yet - no conditional behavior as flexible as with Smarty within the documents. Here's a little hack to apply some Smarty logic anyway, using the More Greetings extension as an intermediary step. However, the PHP library CiviOffice relies on has macro features that might be harnessed to add very similar features as Smarty's to CiviOffice.

What is next?

With “live snippets” CiviOffice already has a small but handy functionality to insert content during the creation of a document. Bumping this up to a full-scale document editor would be a dream. Other dreamable features include, as we said above macro functions, a SearchKit integration (currently already underway) and the connection to external document stores, such as Nextcloud.

Making these improvements happen depends on financial support. Developing this extension in a open and modular way and keeping it up to date with new versions of CiviCRM, PHP or Drupal is something we did (and continue to do so) with a lot of our own resources. If CiviOffice helps you eliminating tedious tasks from your workflow, save time and produce better looking documents easier, please consider making a financial contribution to the development costs. You can reach us at info@systopia.de.

Links

Filed under