Contribute includes four standard forms. As well as creating content, forms are used to approve, archive and update submissions.
Each group of forms is unique for the type of content being created. For example, you'll need a set of forms for events, a set for locations, a set for classifieds etc.
The Create Form
The form used to contribute content includes all of the fields needed to populate an iCM article. In the default contribute example these include:
- Name (article heading)
- Site area (drop-down of parent articles)
- Intro (introductory text)
- Summary (summary text)
- Body (body text)
- A file upload field for an image
- A checkbox group that displays the values of a metadata property used to categorise the article
Any number of fields can be included, their names just need to be added to the mapping section of the configuration End Point.
Parent Article
When users submit content they can decide where in your site's structure it should appear. The drop-down field is populated by a call to the getAvailableEnvironmentsForArticleCreation End Point. This End Point compares the array of article IDs in the main configuration End Point with the current user, only returning articles secured to groups that the current user is a member of (or those not secured at all).
Category
Categories are mainly used by the Event and Service contribute forms. Picking a category adds metadata to the created article, which is then used by other templates, like the Calendar and Service Directory Search to refine results or control the events and services that get displayed.
Users can pick the metadata that will be related to their article (ie the category) using a group of checkboxes. The values of these checkboxes are taken from the values in the metadata group set in the End Point Configuration.
If the content being submitted doesn't use metadata, this field can be removed and the mapping section taken out of the configuration End Point.
Note that some older versions of the contribute form don't use the metadata value set in the End Point. Instead you'll find a custom database query in the checkbox field which holds the ID.
Workflow Action
When the contribute form is submitted it starts a workflow process instance. The Start Workflow Action field defines the following:
Process Definition
This is the name of the process definition to start an instance of. It will be "contributearticlev1" for this version of the product.
Messages
The success, failure and ineligible messages should be changed to something relevant for the contribute product.
Process Variables Function
When a process instance is started by a form submission, the values of the fields on the form are automatically passed to the process instance as process variables. This function adds additional variables to the process instance and must be updated with the values relevant to your iCM installation and this instance of contribute.
function(helper, processVars) {
processVars.CONTRIBUTEARTICLE_PARENTARTICLEID = helper.queryFieldValue("PARENTARTICLE");
processVars.CONTRIBUTEARTICLE_SITEUSERID = helper.getVariable("USERPROFILE").userID;
processVars.CONTRIBUTEARTICLE_CONFIGNAME = "contributeevent";
processVars.CONTRIBUTEARTICLE_APPROVALFORM = "EVENTAPPROVE";
processVars.CONTRIBUTEARTICLE_APPROVALCANDIDATEGROUP = "CONTRIBUTEEVENTAPPROVERS";
processVars.CONTRIBUTEARTICLE_UPDATEFORM = "EVENTUPDATE";
processVars.CONTRIBUTEARTICLE_ARCHIVEFORM = "EVENTARCHIVE";
processVars.CONTRIBUTEARTICLE_COPYFORM = "EVENTCREATE";
processVars.CONTRIBUTEARTICLE_ADDITIONALTASKS = [{
"form": "CREATENEWTHINGINSTANCEV1",
"name": "Create new instance"
},{
"form" : "DEFAULTPRICESV1",
"name": "Default settings"
}];
processVars.CONTRIBUTEARTICLE_CANDIDATEGROUP = "BOOKANDPAYADMIN";
processVars.CONTRIBUTEARTICLE_PROCESSDESCRIPTION = "Event: " + helper.queryFieldValue("NAME");
return processVars;
}
CONTRIBUTEARTICLE_PARENTARTICLEID
This variable holds the value of the article ID picked in the drop-down field. The new article will be created beneath this one. If this process variable isn't provided, the article will be created beneath the
CONTRIBUTEARTICLE_SITEUSERID
Holds the ID (the actual ID set in iCM, not the username) of the current user.
CONTRIBUTEARTICLE_CONFIGNAME
This is the name of this instance of your Contribute product. It must match the name given to the configuration End Point you would like to use. There is no need to provide the full namespace, just the application part of config.environment.application.getConfig. You should have configuration End Points and groups of forms for each type of content that users can create, for example a form group for events, one for locations, one for blog posts etc.
CONTRIBUTEARTICLE_APPROVALFORM
This is the name of the form approvers will use to approve the submission. Leave this field blank (ie an empty string) to disable the approval process and allow contributed content, and updates to it, to go live on your site without being reviewed.
CONTRIBUTEARTICLE_APPROVALCANDIDATEGROUP
The name of the group of website users who will approve new and updated content.
CONTRIBUTEARTICLE_UPDATEFORM, _ARCHIVEFORM and _COPYFORM
If contribute is being used with Self Service and you would like users to be able to update, archive or copy their submissions, these are the names of the forms that the self service template tasks will link to. Leaving a value as an empty string removes the task.
CONTRIBUTEARTICLE_ADDITIONALTASKS
Additional tasks can be made available to users via Self Service. Each new task should be added to the array like:
{
"form": "CREATENEWTHINGINSTANCEV1",
"name": "Create new instance"
}
where "form" is the name of the form that will be linked to from Self Service, and "name" the text of the link. The example above shows how the event scheduling form is included in contribute event.
CONTRIBUTEARTICLE_CANDIDATEGROUP
Users in this group will be able to claim and work on the update, archive, copy and additional tasks.
CONTRIBUTEARTICLE_PROCESSDESCRIPTION
This process variable is used to set the description of the process instance. It populates the value of the "description" field in the process model and is displayed on the Self Service and User Requests articles.
Redirect Actions
Some contribute forms, especially those related to creating events, can redirect a user to another form when submitted. Note that this redirect will not work if you have approvals set up (the newly created article forms part of the URL that gets redirected to, so if it is waiting to be approved the redirect will fail because it doesn't exist yet). The article that will be redirected to is set in the
The Approval Form
The approval form should include all of the fields, with matching names, used on the create form so that their values are visible to approvers. These fields could be set as read-only if you would like to prevent approvers from editing the content.
The form must also include the following two fields:
APPROVALSTATUS
The approval status drop-down field contains the values APPROVED and NOTAPPROVED. Selecting APPROVED will pass the content to the next stage of the workflow, which creates the content in iCM and publishes it on the site. The website user who submitted the content will then be able to carry out any additional actions relating to their submission.
If the submission is NOTAPPROVED (or any other value) the workflow execution returns to the user who submitted the content so that they may make updates and resubmit.
APPROVALCOMMENTS
Approval comments are notes added by the approver that are visible to the user who submitted the content. They should be used to say why content has not been approved for the site.
Workflow Complete Task Action
The final field on the form is a complete task action field. This field includes a process variables function that can be used to update the process description.
The Update Form
The update form has all of the fields of the approval form. A conditional layout on the standard update form holds the approval status and comments field. If approvals have not been configured, this conditional block will be hidden.
The form also includes a Complete Task Action that commits the changes and moves the workflow onto the next stage of the execution.
The Archive Form
The archive form only needs a submit button and Complete Task Action. It is used to complete the archive workflow task. The actual archiving is handled by the workflow process.
Once an article has been archived it has its display property set as "off" and the related workflow instance is terminated. Archived articles cannot be restored by website users. Turning an article back "on" in iCM isn't advisable because there won't be a workflow instance to accompany it.
Share this page
