Installation

Components

The DRM is imported into iCM as part of the Standardised Site Release Notes update process. This will import all of the relevant forms, End Points and the workflow process. The forms can be used to create Default articles - the forms for other content types are included with those products (for example the Service Directory product includes the forms needed to create and approve Service articles).

Basic Set-Up

Before setting up the forms and End Points you'll need to create some users, API keys, and decide where content is going to be created. Note that if you are configuring more than one contribute instance (for example, one for contributed events, another for contributed locations) we recommend creating iCM users and API keys for each.

1. Destination of Submitted Articles

Articles created by Contribute will appear beneath a parent article. Decide which article will act as the parent and note down its ID.

Optionally users can choose where to create their articles. Note down all of the article IDs you'd like users to create articles beneath. Users can only create content beneath articles secured to website user groups they are members of.

The IDs of these articles are added to the configuration End Point.

2. Destination of Submitted Media

Media items created by the Contribute product will be created in a defined media group. We recommend creating a group called "Contributed Media". Create a group and note down its ID.

The ID of this group is added to the configuration End Point.

3. Metadata

If you'd like to be able to categorise the content that is contributed, for example to be used by the Event Search, users will need to be able to attach metadata values to their articles.

Create a metadata group and properties with all of the values you'd like to use and note down the group ID. It will need to be added to the configuration End Point.

Groups can also be nested. In this example the ID of either the "Contribute metadata" or the "Service Directory" group could be added to the configuration and all of the values of all of the properties will appear on the form:

4. iCM Users

The Contribute product creates articles and media items in iCM. To do this it needs an iCM user to act as, via an API key. The user should be given a meaningful name like CONTRIBUTEEVENT. Create an iCM user and note down the username and password.

Contribute users will need sufficient iCM Privileges to be able to create content in iCM, but these should be kept to a minimum. Users should generally be given full article and media privileges, and content roots that only include the single template type and root article ID of the content they will be creating or updating. They should only have access to the media root set in point 2.

5. API Keys

The Contribute product needs access to the API Server's iCM API Worker. This access is granted by creating an API key for each Contribute instance.

Each key should supply default worker credentials that match a user created in point 4. There is no need to define privileges or iCM/website user group authentication.

Make a note of your new API key as it will need to be added to the configuration End Point.

6. Site Users

For website users to be able to create content using Contribute they will need to be members of a site user group called CONTRIBUTE. This is the group name set in the workflow process model. You'll also need to add the ID of this group to the configuration End Point.

7. Approval Users

Unlike standard iCM approvals, the approvers of content created via Contribute are also website users. The name of this approver group will be added to the contribute form. Create a user group and add the users who will carry out approvals to it.

Create the Configuration End Point

The End Point import includes example configuration End Points at goss.contribute.v1.default. Copy one of these End Points and move your copy into the correct config.environment.application namespace for where you are working. The "application" part of the namespace should relate to the type of content being created:

Follow the information in End Point Configuration to complete the configuration, using all of the IDs created in the points above.

Update the Forms

The main field to update in the contribute form is the Start Workflow action. You'll need to enter the "application" part of your config End Point's namespace and check that all of the form names used for user tasks and approvals are correct. See Form Configuration for more information.

Also check that the "Editor stylesheet" property of any WYSIWYG fields used on the contribute form is correct.

Double Check the Mappings

The default configuration End Points include article mappings for the fields in the example forms. If you've changed any form fields, check the mappings are correct.

The media mappings will need to be updated too. Most iCM installations will have an image media type called "image" but the component names will vary.

Article Setup

Create an article using the Forms Service template and relate the contribute form to it. Secure the article to the user group you'd like to be able to use it. The users in this group should also be members of the CONTRIBUTE group who are eligible to start the contribute workflow.

There's no need to make the other forms available using articles on your site, these are linked to directly from workflow tasks

If you are using Self Service or User Requests, update those articles to include the contribute workflow process.