Working with custom content types

A previous page explained how to configure uploader-plus to prompt for the metadata of the cm:content type. This was a simplified example because cm:content is a standard type and its forms are already configured in the basic Alfresco installation. Not much work left for us to do other than just use it!

But if you're interested in metadata during the upload, cm:content is certainly too generic and you're probably already looking at custom content types (like "invoice", "order", "appraisal" or "record") that make more sense in your application domain. In this page we'll see how to setup a form for this kind of content.

Note: the procedure described in step 1 will probably not work with recent versions of Alfresco. Alfresco Workdesk used to be compatible with Alfresco 4.2.x but hasn't been maintained since. The reference to Alfresco Workdesk is left for consistency with the description and the screenshots. In your tests, please use a different content model.

Step 1: install the example content model

For clarity, we're going to use the sample HR content model found in Alfresco Workdesk:

• download Alfresco Workdesk community 4.2.0-2014-06-30
• unzip the file
• read the instructions at bin/SampleApplication/HumanResourcesApplication/readme.txt
• install the custom model (using the install-workdesk-hr.bat or install-workdesk-hr.sh script)

The model will be installed in tomcat/shared/classes/alfresco/extension/workdeskHRContentModel.xml of your Alfresco installation. In this page we're going to use "owd:hrdocument", one of the provided content types.

Step 2: set up an upload folder

Following the configuration instructions, set up an upload folder anywhere you like (e.g. /Sites/swsdp/documentLibrary/Agency Files) and choose owd:hrdocument as the allowed type.

Navigate to the folder and upload a document. The following form will be shown.

A rather long form! This form is generated automatically by Alfresco. Alfresco simply looks at the content type, finds all the properties and creates a field for each property. Borrowing the concept from Java, Alfresco can generate a form by performing some kind of "reflection" on the content type. No configuration is necessary other than defining the content model.

This automatic generation may sound good at first but is has its limits. A closer inspection of the form reveals that the properties are in random order and that some properties (modified/created date, creator/modifier) should not be offered to the user but kept hidden and populated by the system behind the scenes.

All these considerations make a case for configuring the form explicitly, rather than relying on Alfresco's automatic generation.

Step 3: inspect the content type

Open tomcat/shared/classes/alfresco/extension/workdeskHRContentModel.xml and find the definition for owd:hrdocument. For convenience, the relevant fragment is shown below:

<type name="owd:hrdocument">
  <title>HR Document</title>
  <description>HR documents related to certain employee</description>
  <parent>cm:content</parent>
  <properties>
    <property name="owd:documentPersonnelNumber">
      <title>Personnel Number</title>
      <type>d:text</type>
      <constraints>
        <constraint ref="owd:allowedPersonnelNumbers" />
      </constraints>
    </property>
    <property name="owd:hrDocumentType">
      <title>Type</title>
      <type>d:text</type>
      <index enabled="true">
        <atomic>true</atomic>
        <stored>false</stored>
        <tokenised>false</tokenised>
      </index>
      <constraints>
        <constraint ref="owd:allowedHrDocumentTypes" />
      </constraints>
    </property>
    <property name="owd:documentComment">
      <title>Comment</title>
      <type>d:text</type>
    </property>
  </properties>
  <mandatory-aspects>
    <aspect>owd:AspectDate</aspect>
  </mandatory-aspects>
</type>

The type defines three properties:

• owd:documentPersonnelNumber ("Personnel Number")
• owd:hrDocumentType ("Type")
• owd:documentComment ("Comment")

It also imports the mandatory aspect owd:AspectDate, from which it gains two other properties:

• owd:EntryDate ("Entry Date")
• owd:DispatchDate ("Dispatch Date")

Owd:hrdocument inherits from cm:content and, following the inheritance chain, from cm:cmobject and sys:base. Through inheritance, owd:hrdocument acquires approximately 10 more properties.

Also Alfresco automatically attaches the cm:titled an cm:author aspects to any content uploaded on the system, which provide three more properties.

Some of the properties are system properties (sys:store_protocol, etc) and should never be displayed. Some other properties are populated automatically (cm:created, etc) and should not be offered for input to the user. Other properties may make sense to your underlying application logic but are of little value in the user interface.

Your task is to choose the subset of properties that must really be entered by the user and so should be displayed in a form. Here, let's assume we want to display the following properties:

• cm:name
• cm:title
• cm:description
• owd:documentPersonnelNumber
• owd:hrDocumentType
• owd:documentComment

We're now ready to define a form.

Step 4: define the form

Open your share-config-custom.xml configuration file under /tomcat/webapps/share/WEB-INF/classes/alfresco/web-extenstion/ and add the following fragment:

<config evaluator="model-type" condition="owd:hrdocument">
  <forms>
    <form>
      <field-visibility>
        <show id="cm:name" />
        <show id="cm:title" force="true" />
        <show id="cm:description" force="true" />
        <show id="owd:documentPersonnelNumber" />
        <show id="owd:hrDocumentType" />
        <show id="owd:documentComment" />
      </field-visibility>
      <appearance>
        <field id="cm:name">
          <control>
            <control-param name="maxLength">255</control-param>
          </control>
        </field>
        <field id="cm:title">
          <control template="/org/alfresco/components/form/controls/textfield.ftl" />
        </field>
      </appearance>
    </form>
  </forms>
</config>

The core of the form definition is the field-visibility element, which lists the six properties that we decided to show. Other details about the xml are the following:

• The force="true" attribute is required on cm:title and cm:description because these belong to the cm:titled aspect, which is attached with a special mechanism.
• The appearance elements is optional and is required only if you want to customise the appearance of some of the fields.
• The appearance of cm:name is customised to limit the input to 255 characters, a constraint of file names.
• The appearance of cm:title (which is of type mltext – multilingual text) is customised to be displayed using a text field instead of the default text area.

Fields can be customised in many other ways and it is even possible to use a completely custom form template. The subject is broad, for more information see the Alfresco documentation.

Step 5: test the form

Save share-config-custom.xml and restart Alfresco. Go to the upload folder and start an upload. This time you'll be prompted by a nice, compact form:

Notice that the form definition is used not only by uploader-plus during the upload, but also by Alfresco during other operations where an owd:hrdocument is involved. To test this, upload a document, then select "Edit properties" from the document's list of operations: the same form will be used.

Conclusions

Attaching metadata to documents is an important factor in maintaining a high quality repository. Documents without metadata are easily misclassified or lost. Documents with metadata are better classified and are more easily available for later retrieval.

Uploader-plus encourages this good practice by presenting users with effective, visually pleasant, customisable forms.