The official documentation is at: http://docs.alfresco.com
IMPORTANT: This document details dynamic model management features and supporting changes, such as a dynamically configurable web client UI. These features are currently available in Alfresco 3.x releases. As always, any and all feedback is welcome via the forums.
IMPORTANT: This steps are for web-client only, and won't work for the Share interface (see this forum post).
Table of Contents
- 1 Background
- 2 Introduction
- 3 Features
- 3.1 Dynamic models
- 3.2 Dynamic web client
- 3.3 Dynamic workflow process definitions
- 3.1 Dynamic models
- 4 Clustering
- 5 Examples
- 6 References
The Alfresco Repository supports various types of customisation, including the ability to define custom models and workflows. The Alfresco Web Client supports a customisable UI configuration. These customisations are typically deployed via the alfresco/extension folder and require the Alfresco server to be re-started to take effect.
The dynamic model feature enables dynamic customisation of models without requiring a restart of the Alfresco server, and is also applicable to a multi-tenant environment. This also includes dynamic reloading of the web client UI customisations.
The new features include:
- deployment/undeployment of custom models (& messages) to/from the Alfresco Data Dictionary
- deployment/undeployment of custom workflow (process) definitions to/from the Alfresco Data Dictionary
- deployment/undeployment of custom web client extensions to/from the Alfresco Data Dictionary
Dynamic custom models are stored in the new 'Models' space (Company Home -> Data Dictionary -> Models). The associated message resource bundles are stored in the new 'Messages' space (Company Home -> Data Dictionary -> Messages). Refer to the Data Dictionary Guide for more details on defining a new custom model.
Deploying and activating a custom model
Upload a custom XML model file to the 'Models' space. By default, the model will not be active unless the 'Model Active' checkbox is selected during the upload. To activate a previously inactive model, select 'View Details' and then select the 'Modify' properties icon. In the 'Modify Content Properties' page, select the 'Model Active' checkbox.
Updating and re-loading custom model
Edit or update the XML model file. If the model is active then it will be re-loaded. If the file is checked-out then the working copy will be ignored until such time that the file is checked-in.
NOTE: Only incremental updates are supported for an active model. If the update attempts to delete a type, aspect, property (etc) then the upload will fail. The reason for the failure can be seen in the Alfresco console, although the web client may (currently) display a more cryptic error message such as 'A system error happened during the operation: Unknown Exception in Transaction.'
Deactivating or undeploying a custom model
To deactivate a model, select 'View Details' and then select the 'Modify' properties icon. In the 'Modify Content Properties' page, unselect the 'Model Active' checkbox.
To delete a model, select Delete.
NOTE: The model can only be deleted if there are no existing usages, otherwise the delete will fail. The reason for the failure can be seen in the Alfresco console, although the web client may display a more cryptic error message such as 'A system error happened during the operation: Unknown Exception in Transaction.' or 'Unable to delete File due to system error:'. 'No existing usages' includes deleted items that are still accessible through Manage Deleted Items in the user profile and settings page.
Deploying message resources
Upload the custom resource bundle by uploading each of the message property files (for all locales) to the 'Messages' space. The messages will not be applied until they are explicitly re-loaded (see next section) or when the server is restarted.
Updating and re-loading message resources
If the message property files are edited or updated then they can be dynamically re-loaded by using the repo admin console via:
The command 'reload messages <resource bundle basename>' will cause the message resource to be re-registered. These will then be re-loaded the next time the user logs in (with a corresponding locale). If the files are checked-out then the working copies will be ignored until such time that they are checked-in.
NOTE: Unlike dynamic models, the property files do not have an active/inactive flag. Hence, even if you do not dynamically re-load the message resources after the update, they will still be registered and loaded next time the server is restarted.
Using the Repository Admin Console
The Repository Admin console can be used (as an alternative to the Web Client) to deploy, activate and deactivate models. It can also be used to deploy, re-load and undeploy message resource bundles.
Type 'help' for more details.
Edit log4j.properties and comment-in the following property:
Dynamic web client
Dynamic web client customisations are stored in the new 'Web Client Extension' space (Company Home -> Data Dictionary -> Web Client Extension). This space simply provides an additional source (in this case, a repository location) for loading and overriding the web client configuration. Refer to the Web Client Customisation Guide for more details on customising the web client.
Deploying web client customisations
Upload a custom 'web-client-config-custom.xml' file to the 'Web Client Extension' space. The custom configuration will not be applied until it is explicitly re-loaded (see next section) or when the server is restarted.
IMPORTANT The custom config file must be named 'web-client-config-custom.xml'. The config load order is specified in 'web-client-application-context.xml'.
Updating and re-loading web client configuration
If the 'web-client-config-custom.xml' file has been added, edited or updated, it can be dynamically reloaded by using the web client config console via:
This has a single command 'reload' which will cause the web client configuration to be re-loaded. Depending on your setup, you will see console output such as:
<Built-in evaluators> ---> OK
classpath:alfresco/web-client-config.xml ---> OK
classpath:alfresco/web-client-config-dialogs.xml ---> OK
classpath:alfresco/web-client-config-wizards.xml ---> OK
classpath:alfresco/web-client-config-properties.xml ---> OK
classpath:alfresco/web-client-config-navigation.xml ---> OK
classpath:alfresco/web-client-config-wcm.xml ---> OK
classpath:alfresco/web-client-config-actions.xml ---> OK
classpath:alfresco/web-client-config-forum-actions.xml ---> OK
classpath:alfresco/web-client-config-wcm-actions.xml ---> OK
classpath:alfresco/web-client-config-workflow-actions.xml ---> OK
classpath:alfresco/extension/web-client-config-custom.xml ---> Skipped - not available
workspace://SpacesStore/app:company_home/app:dictionary/app:webclient_extension/cm:web-client-config-custom.xml ---> OK
If the file is checked-out then the working copy will be ignored until such time that is it checked-in.
NOTE: Unlike dynamic models, the configuration file does not have an active/inactive flag. Hence, even if you do not dynamically re-load the configuration after the update, it will still be loaded next time the server is restarted. If the config is invalid (e.g. cannot be parsed) then it will be skipped during loading and an error will be logged.
Deploying web client properties
Upload a custom 'webclient.properties' file to the 'Web Client Extension' space. These properties will be applied for the next user session/login.
Reloading web client properties
A user should logout and then login to force a refresh of the messages.
Dynamic workflow process definitions
Alfresco currently supports the ability to manage workflow process definitions dynamically via the Workflow Console, assuming the definitions are using existing task models and messages. With the introduction of dynamic models, it is now possible to dynamically manage new workflow process definitions using new task models and messages and client configuration. In addition, it is also possible to deploy workflow definitions directly from a repository location.
Deploying a workflow process definition
Upload a custom XML process definition file to the 'Workflow Definitions' space. By default, the process definition will not be deployed unless 'jbpm' is entered for the engine id and the 'Workflow Deployed' checkbox is selected during the upload.
Updating a workflow process definition
Edit or update the XML process definition file. If the definition is already deployed then it will be re-deployed.
Undeploying or deleting a workflow process definition
To undeploy a process definition, select 'View Details' and then select the 'Modify' properties icon. In the 'Modify Content Properties' page, unselect the 'Workflow Deployed' checkbox.
To delete a process definition, select 'Delete'.
WARNING: In both cases, all process definition versions in JBPM will be undeployed and all active 'in-flight' workflows will be deleted !!! This is equivalent to issuing the 'undeploy definition <definition name>' command in the workflow console. Please be careful when deploying and/or deleting workflow definitions - no warning will be given in the web client.
Using the Workflow Console
The Workflow console can be used (as an alternative to the Web Client) to deploy and undeploy process definitions. It has been available since Alfresco 1.4, and provides commands for interacting with workflows. Its primary use is to test newly developed workflow definitions. However, it also supports the debugging/diagnosis of current 'in-flight' workflows.
Type 'help' for more details.
The dynamic model and web client configuration features have been designed and implemented to work in a clustered configuration.
Example 1 (example model)
1. deploy model 'exampleModel.xml' to the 'Models' space and select 'Model Active'
2. upload a 'web-client-custom-config.xml' to the 'Web Client Extension' space, that contains the customised UI
Please refer to the 'web-client-custom-config.xml' found in the /alfresco/extension directory, and comment-in the last 5 config sections, as appropriate
3. re-load the custom UI by issuing the following command from the Web Client Config console:
This can be found at http://host:port/alfresco/faces/jsp/admin/webclientconfig-console.jsp
4. upload a 'webclient.properties' to the 'Web Client Extension' space, that contains the following:
# web client custom I18N message properties
# example model
# see display-label-ids added to the web-client-config-custom.xml sample
To verify the changes ...
5. logout / login
6. Use 'Add Content' to upload some content, and during the upload change the 'Content Type' from 'Content' to 'Standard Operating Procedure'. Use 'Advanced Search', enter some search text to 'Look For' and also select 'More Search Options' and then 'Standard Operating Procedure' as the search 'Content Type'
NOTE For more details on the example model sample, refer to Data Dictionary Guide. The deployment configuration file 'example-model-context.xml' (as mentioned in step 4) is not required when using dynamic models.
Example 2 (lifecycle workflow)
1. deploy model 'lifecycleModel.xml' to the 'Models' space and select 'Model Active'
A copy of the 'lifecycleModel.xml' can be found in the /alfresco/extension directory
2. deploy workflow definition 'lifecycle_processdefinition.xml' to the 'Workflow Definitions' space, enter 'jbpm' engine id and select 'Workflow Deployed'
A copy of the 'lifecycle_processdefinition.xml' can be found in the /alfresco/extension directory
3. deploy workflow messages 'lifecycle-messages.properties' to the 'Messages' space
A copy of the 'lifecycle-messages.properties' can be found in the /alfresco/extension directory
4. reload message resource bundle - by issuing the following command from the Repository Admin Console
reload messages lifecycle-messages
To verify the changes ...
5. logout / login
6. try to start an advanced workflow on some content - notice that 'Lifecycle Review & Approve ...' workflow is listed in addition to other two standard workflows
NOTE For more details on the lifecycle workflow sample, refer to WorkflowSample Lifecycle. The deployment configuration file 'lifecycle-workflow-context.xml' is not required when using dynamic models.