Installation and Administration Guide

  Written by The Jahia Team
 
Sysadmins
   Estimated reading time:

Introduction

What Is Jahia Workspace Factory 3.0?

Built on Jahia's acclaimed core content platform, Digital Factory, Workspace Factory 3.0's feature scope has been designed to simplify everyday life for digital teams. Collaboration, document sharing and editing, and content publication is efficient - and happens without the burden of learning a complex enterprise content management (ECM) solution.

Who Is This Guide Intended For?

This guide is intended for the people in charge of the installation and / or administration of a Jahia Workspace Factory 3.0 server, primarily the technical administrators in your organization. It was designed to be used by beginners as well as by the most seasoned experts.

This guide does not cover the daily use of Workspace Factory 3.0 by your co-workers. You will find this information in the "Jahia Workspace Factory 3.0 User Guide".

Workspace Factory 3.0 Installation

Jahia Workspace Factory 3.0 is available as a downloadable package for Jahia Digital Factory Enterprise Distribution.

In order to use Jahia Workspace Factory 3.0, a pre-existing Jahia Digital Factory Enterprise Distribution installation is required.

Please refer to the Jahia Digital Factory Administration Guide on the Jahia web site for instructions on how to install Jahia Digital Factory in your organization.

Supported Environments

Jahia Workspace Factory 3.0 has been tested and is supported on a wide variety of operating environments (Windows, Linux, Mac OS), in order to correspond to the diversity among our customers' information systems.

To view all supported stacks and versions, which are the same as those supported for Jahia Digital Factory Enterprise Distribution, please refer to the Jahia Website:

https://www.jahia.com/documentation-and-downloads/developers-downloads/system-requirements

Installing Add-Ons

If you want to take advantage of the document and image preview features in Workspace Factory 3.0 for the most frequent formats (Microsoft Office, PDF, images, etc.), you need to have the following add-ons configured during your Jahia Digital Factory installation.

Add-Ons

Office document converter

To use the converter service you need OpenOffice / LibreOffice v3 or higher installed (the latest stable 3.x version is recommended).

Workspace Factory 3.0 may work with older OpenOffice versions (e.g., 3.3 and even 3.2) but we recommend OpenOffice 3.4 or higher.

Document viewer

To view documents in Workspace Factory 3.0, you need SWFTools (pdf2swf) v0.9.1 or higher.
http://www.swftools.org/download.html

Video thumbnails service

Install ffmpeg 0.9.2 or higher to display video thumbnails.
http://ffmpeg.org/download.html

Image conversion

ImageMagick 6.6.x or 6.7.x (6.8.x may be supported but it has not been tested yet).
http://www.imagemagick.org/

Configuration

If you have no pre-existing Jahia Digital Factory installation, please make sure that you enter the path for each add-on during Digital Factory installation when the installer prompts you.

If you have an existing Jahia Digital Factory installation or wish to verify the installation of the add-on viewers, please make sure that the following file located in your Jahia web server:

digital-factory-config/jahia/jahia.properties

is correctly configured. It should contain following lines, uncommented (no # before the line).

The paths to the executables may vary depending on your installation. Windows paths may be entered using / or \\ slashes.

documentConverter.officeHome = /usr/lib/openoffice
jahia.dm.viewer.pdf2swf = pdf2swf
jahia.dm.thumbnails.video.ffmpeg = ffmpeg
imageMagickPath = /usr/bin:/usr/local/bin:/opt/local/bin

Installing Jahia Workspace Factory 3.0

Jahia Workspace Factory 3.0 being a module package for Jahia Digital Factory, you need to have a pre-existing Jahia Digital Factory Enterprise Distribution installation.

  1. Log on to Jahia Administration as Server Administrator rights.
    http://localhost:8080/administration
  2. Go to System Components > Modules. Click on "Available Modules"
  3. Select the "Enterprise Distribution Workspace Factory" package from the list. To find it more quickly, you can use the Search feature on this page and type "work" in the search field. Click on the Download button to Download and Install it.
  4. Wait a few moments while the module is being deployed.

You're now ready to use Workspace Factory 3.0 on your server.

Uninstalling Workspace Factory 3.0

If you need to uninstall Workspace Factory 3.0, go to Jahia Digital Factory Administration > System Components > Modules and display the installed Workspace Factory modules. To do so easily, you can type "works" in the search field.

The modules are called "Workspace Factory" and "Workspace Factory Management".

Stop the modules if they were started and confirm.

Click the "Undeploy" button for "Workspace Factory" and confirm. Due to module dependencies, this also uninstalls the other module "Workspace Factory Management".

Workspace Factory 3.0 Administration

Login Screen

Log in to Workspace Factory 3.0 using the "root" account and the password you chose for Jahia Digital Factory.

Unless you changed the URL or the port of the installation, Workspace Factory 3.0 is available through http://<servername> or http://<servername>/wsfactory

For the purpose of this guide, the server name will be "localhost".

You will be taken to your Workspace Factory 3.0 profile page. By default, the user interface is displayed in English.

To display the administration menus in a different language, click on "edit profile" then select your preferred language in your profile and click OK to save the change.

The user interface, including all menus, is now displayed in the language of your choice.

Managing Users

Before configuring any Workspace Factory 3.0 instances and spaces, it is preferable to set up a base of authorized users.

You can create users manually or import files containing existing user profiles.

To configure users, select the "Manage users" option in the Administration menu. A new tab opens with the Users administration panel. This is the standard Jahia Digital Factory Users Administration screen.

Creating a User

To manually create a user, click on the "Create new user" button.

Enter the basic information for the profile (username, first name, last name, email address, organization, preferred language, password, email notifications) and click Add to save the profile.


 

Importing Users

If you already have a list of users in CSV format, you can import all the users in this list directly into Workspace Factory 3.0. Click on the "Bulk create users" button.

Select the CSV file on your computer, specify the field separator if necessary and click OK.

The list of users will be displayed in Jahia Workspace Factory 3.0.

Editing A User's Basic Properties

In the user management interface, you can edit the basic properties of a user account. However, you cannot edit the user's detailed Workspace Factory 3.0 profile (picture, skills, function etc.). Only the user can do this, from their Profile/Dashboard page (to learn more about this, please refer to the Jahia Workspace Factory 3.0 User Guide).

Click the Edit icon corresponding to the user whose properties you want to modify.

The editable fields are the same as the ones displayed when creating the user account, except for the username, which cannot be modified. When your changes are finished, click Update.

Browsing Users in the Directory

The Users directory displays the profiles of all registered users on the server. To access it, click on "Users directory" in the navigation bar at the top of the page.

You can display users whose names start with a specific letter or create a search.

Click on a user to display their detailed profile.

Editing a User's Detailed Information

As an administrator, you can edit the basic properties of a user account via the administration interface.

However, only the user themselves can update the detailed information on their Workspace Factory profile (picture, skills, function etc.).

To learn more about this, please refer to the Jahia Workspace Factory 3.0 User Guide.

Removing Users

If you wish to remove only one user, click the red cross icon next to their username.


If you need to remove several users, check the box next to their username and click the "Remove Selected Users" button.

Deleting users through these screens deletes them from Jahia Digital Factory. Proceed with caution.

Defining and Managing Categories

Define a tree structure with categories that are adapted to your organization, your industry or your profession.

Categories make it possible to sort your organization's documents into a thematic tree structure. It gives a more orderly and hierarchical description of documents and is more restrictive than tags since the list of available categories is entirely managed by the administrator, whereas tags can be added freely by users when sharing documents.

For each Workspace Factory 3.0 workspace, the Owner will be able to choose a root category for their space from the global category tree: the members of the space will be able to use this category and all sub-categories for their documents and notes. They will not be able to access the other categories in the tree structure.

Select the "Manage categories" option in the Administration menu.

Creating a Top-Level Category

It is important to design the category tree in collaboration with the head managers of each department in your organization, so that the documents can be shared with the best possible description.

Click on the "New category" button to create a top-level category. You can create several top-level categories but a workspace can only use one top-level category.

Enter a title for your category and click on the "Create category" button.

Creating a Sub-Category

Click on the "+" icon to add sub-categories to your top-level category.

Enter a title for the sub-category in the pop-up box and click on the "Create category" button.

You can repeat this process for lower-level categories (sub-sub categories etc.).

There is no limit to the number of category levels. Good practice tends to demonstrate that in most cases, a depth of 2 or 3 levels is the most efficient compromise between precision and ease of use.

Deleting a Category

To delete a category, whatever its level, click on the "-" icon and confirm the deletion. All the sub-categories of this category will also be deleted.

Managing Workspace Factories and Workspaces

Workspace Factories make it possible to manage several workspaces together and define default global permissions for all these spaces through authorized user groups.

In smaller organizations, a single Workspace Factory 3.0 is usually enough.

For larger organizations, it may be necessary to organize the various spaces into several Workspace Factories with specific rights.

Select the "Workspace Factory management" option in the Administration menu.

Creating a Workspace Factory

Click on the "Create a new Workspace Factory" button to create a new Workspace Factory. Each workspace factory is a container for workspaces and can have its own set of permissions and users.

Enter a meaningful title for your Workspace Factory and define a shortened name ("Web project key") that will appear in the URL of the workspaces. Optionally, you can give more details about the instance in the "Description" field.

For example, the title can be "ACME Space Marketing" and the associated web project key "mktg".

If your server is associated with a domain name, e.g. www.acme-space.com, enter this name in the "Web project host name" field to establish the correspondence.

Each instance has an actions menu with four icons:

  • view workspaces;
  • edit general settings;
  • define Workspace Factory Managers;
  • manage user groups.


Each Workspace Factory can have its own administrator. To change the administrator of a Workspace Factory, click on the third icon (person) in the action bar and select the new admin.

Creating Workspaces


To create a new space, go to the page of the selected Workspace Factory by clicking on its name or on the blue arrow in the actions menu.

Click on the "Create New Workspace" button.


Enter the name for the new space and a detailed description and click on "Create".

The description will give users more details about this space, in case they would like to become a member.

After a few moments, the new space is created. By default, the system administrator (root) is an Owner in all spaces. Select a designated Owner for this space by entering their name and then confirm.


Change the permissions by clicking on their current role (by default: Editor) in order to assign them the Owner role in this space and then click OK. The new space can now be managed by the Owner that you have just defined.

Appointing Workspace Factory Managers

You can appoint one or more Managers for each Workspace Factory. Workspace Factory Managers have the necessary permissions to create / edit / delete workspaces in their own Factory.

To add a manager, enter their name in the "Can create Workspaces" field on the page of the instance.

To remove a manager, click on the "Remove" link.

Deleting a Workspace Factory

If you need to permanently delete one or more instances, go to the "Manage Workspace Factories" page, select the instances to be deleted and click on the "Delete" button.

Deleting a Workspace Factory is permanent and cannot be undone. All the workspaces related to this instance will be permanently destroyed and cannot be restored afterwards.

If you are sure of your choice, confirm.

Using Groups

For each Workspace Factory, you can define which user groups are allowed to display the Factory and the list of related workspaces. By default, users cannot view any Workspace Factory if they are not members of a workspace.

Click on the group icon in the actions menu to access the group management interface for this instance.

Creating a Group

To create a group, click on the "Create new group" button.

Enter a name for your group and click Add.

Adding Members to a Group

By default, newly created groups are empty.

Click on the group's name and the "Edit Membership" button.

In the list, select one or more users you want to add to the group by checking the box next to their username to add them to the group. You can browse the list or search for a specific user via the Search field. To save your changes, click "Save".

Removing Members from a Group

In the list, select one or more users you want to remove from to the group and uncheck the box next to their username to remove them from the group. You can browse the list or search for a specific user via the Search field. To save your changes, click "Save".

Workspace Factories and Groups

Each Workspace Factory instance has its own user groups. If you create a "Marketing" group in a Factory, it will not be available in the other ones.

 

Users who are not part of an authorized group for a Workspace Factory will not see the Factory or the related workspaces.

Removing a Group

Select a Workspace Factory in the "Manage Workspace Factories" screen and click the Groups icon in the actions bar.

To remove a group from this Workspace Factory, click on the red cross icon next to its name and confirm on the next screen. Only the group is removed; the user accounts are not deleted.

Configuring the Email Gateway

The email gateway makes it possible to enable one of the most acclaimed features in Workspace Factory 3.0 - the ability to send Notes or Documents directly into a workspace via email.

Once the gateway has been configured, the Owner of each workspace can decide to activate or not the reception of documents and notes via email for their space as well as the alias to be used for that purpose.

The email account used as the gateway can be either a Gmail account or an IMAP / POP3 account.

Select the "Email settings" option in the Administration menu.

With a Gmail Account

The easiest way to configure the gateway is to use a Gmail account. If you do not have an account for the gateway, you can simply create a Gmail account here: http://mail.google.com.

If the email gateway is a Gmail or Google Mail account, select the "Google Mail" option, enter the username and password for the account and Submit.

With an IMAP / POP Account

If your email gateway is an IMAP or POP account, select the "Custom IMAP / POP3 configuration" option and fill in the fields with the information for this account.

Select the protocol (IMAP, POP or their secured versions IMAPS or POPS) and enter the name of the email server. Only change the port number if it differs from the default port (110 for POP, 143 for IMAP, 995 for POPS and 993 for IMAPS).

Define a polling interval. By default, this interval is set to 60 seconds.

Choose whether you want to delete the messages from the server once they have been processed by Workspace Factory.

Enter the username and password for the account and Submit.

Advanced Administration Features

Exporting Workspace Factories

You can export an existing Workspace Factory configuration (factories, workspaces, shared documents, users and their associated roles) for backup purposes or in order to import them.

You can export one or more Workspace Factories via the "Manage Workspace Factories" page that can be accessed from the Administration menu.

  • Export: all users and roles are exported, along with workspaces. However, only the documents/files that are not locked for edition (whether manually or by a validation workflow) will be present in the exported file.
  • Export (Staging content): all users and roles are exported, along with workspaces. All documents/files, whether locked or unlocked, including those involved in a validation workflow, will be present in the exported file.

Workspace Factory 3.0 generates a .zip archive that is automatically sent to your browser for download.

This file can then be imported on any other Workspace Factory 3.0 server.

Alternatively, you can log in to the Jahia Digital Factory administration interface as a Server Administrator (e.g root) from the following address: http://localhost:8080/administration/

Go to the "Web Projects" administration panel. Select the Workspace Factories you want to export. It offers similar functionalities.

Importing Workspace Factories

You may need to import an existing Workspace Factory data export (users, factories, workspaces, documents, etc.).

Log in to the Jahia Digital Factory administration interface as a Server Administrator (e.g., root) from the following address: http://localhost:8080/administration/ and go to the "Web Projects" administration panel.

Click the "Choose file" button to select a Workspace Factory export file on your computer or enter the network path to the file if it is located on your corporate network.

Click "Import" in order to analyze the contents of the file.

After a few moments, the Workspace Factory 3.0 sites or instances found in the export file are displayed, as well as shared content users and roles. Make sure Users and Roles archives are selected. Check the boxes for the Workspace Factories you wish to import; uncheck the boxes for those you do not want to import. Click "Next" and wait for the import to finish.

The import process can be very long, up to several dozen minutes. Your imported projects now appear in the list of Web Projects.

Customizing Roles

Workspace Factory 3.0 comes with 4 major default roles: Collaborator, Editor, Editor and Validator and Owner. For more details about these roles and the associated permissions, please refer to the "Jahia Workspace Factory 3.0 User Guide". However, you may need to fine-tune the permissions associated with some roles.

Access to this functionality is reserved for experienced Jahia administrators. An incorrect configuration may cause severe malfunctioning of the system and could result in the impossibility for some users to access their data.

Log in to the Jahia Workspace Factory 3.0 administration interface as a Server Administrator (e.g., root) from the following address: http://localhost:8080/administration/

Go to the "Users and Roles">"Roles and Permissions" administration panel.

All roles pertaining to Workspace Factory 3.0 are identified with the prefixe "docspace-"

The major roles are the following:

  • docspace-collaborator=Collaborator
  • docspace-editor = Editor
  • docspace-editor-validator = Editor and Validator
  • docspace-owner = Owner

Select the role that you want to modify and edit it by clicking its name or the Edit icon on the same line.

Review the role's Permissions by browsing the tabs and scopes. The tree of all the permissions for this role will be displayed. If you want to modify a permission, check or uncheck the corresponding box. When your changes are finished, click on "Save". These changes will be applied to all Workspace Factory 3.0 instances for all users with this role.

Optimizing System Performance

Newer hotfix releases of Jahia Workspace Factory 3.0 frequently include performance improvements; we recommend upgrading your environment to these hotfix releases.

To get the best performance from Jahia Workspace Factory 3.0 for the specific needs and usage patterns of your organization, you may need to tweak the installation parameters. In this section, you will find a range of fine-tuning parameters recommended by our engineers.


Storing binary files (at install only)

During step 9 of the Custom installation process, an option allows you to either check or uncheck the box "Store binary data in the database".

According to the Apache Jackrabbit wiki (http://wiki.apache.org/jackrabbit/DataStore#File_Data_Store), "FileDataStore is usually faster than the DbDataStore, and the preferred choice unless you have strict operational reasons to put everything into a database."

We recommend you leave the "Store binary data in the database" checkbox unchecked.

This choice must be made when installing Jahia Digital Factory. You cannot change the store implementation mode at a later time, unless one makes an export-import of the repository data. When using a FileDataStore in cluster, a shared file system needs to be used, where all cluster-nodes point to.

By default, the datastore is located at digital-factory-data/repository/datastore.

You can override that location (and move the folder to any other place, when the Digital Factory server is shut down), if needed, by changing the path value for jackrabbit.datastore.path in the jahia.properties file, for example:

# JCR file datastore path in case of the file-based binary storage
jackrabbit.datastore.path = /opt/DigitalFactory-7/share/datastore

Increasing Bundle Cache Size

Another recommendation is to increase the value of the BundleCacheSize setting in WEB-INF/etc/repository/jackrabbit/repository.xml and all workspace.xml files (digital-factory-data/repository/workspaces/(live|default)/workspace.xml).

The default value could be not enough for large production systems. It should be increased to at least 256MB.

Increase the BundleCacheSize param of PersistenceManager by doing the following:

For each PersistenceManager element in WEB-INF/etc/repository/jackrabbit/repository.xml and in all workspace.xml files (under digital-factory-data/repository/workspaces/), uncomment/add or modify the value of the following parameter:

<PersistenceManager ...>
    <param name="bundleCacheSize" value="256" />
</PersistenceManager>

For the PersistenceManager element under the Versioning element, the bundleCacheSize can usually be 2 - 4 times smaller than the one under the Workspace element.

OpenOffice troubleshooting

Sometimes there can be problems connecting to OpenOffice.

You can view this in the logs, where it says that the OfficeManager is currently stopped. In that case:

  • Shutdown the Jahia Workspace Factory 3.0 server.
  • If applies, kill the old Office process(es), which may still be running.

Memory issues

On OutOfMemoryErrors it is also recommended to restart the Jahia Workspace Factory 3.0 server as soon as possible, as it could lead to data corruption.

Concomitantly open files (Linux only)

On Linux, it is important to raise the number of concurrently open files as otherwise one can quickly run into "Too many open files" exceptions raised by the operating system.

We recommend to set especially the next two parameters to unlimited.

nofiles(descriptors) unlimited
coredump(blocks) unlimited