Each set of contribute forms will need its own configuration End Point. The configuration End Points follow our standard naming conventions.
For example, a contribute instance set up for contributing event articles in a development environment will have the namespace config.dev.contributeevent.getConfig.
Configuration End Points should be created for every contribute instance and be given meaningful names that relate to the type of content they are contributing. This name is added to the form used to create content in the Start Workflow field's process variables function - see Form Configuration for more information.
The getConfig End Point
This example shows the standard configuration used by a Contribute Event instance.
{
"apiKey": "3E123456-A123-B123-C123-AA1AAF123456",
"rootArticleID": 544,
"rootArticleIds": [{
"env": "Staff Events",
"articleId": "1700"
}, {
"env": "Public Events",
"articleId": "1701"
}],
"rootContributeGroupID": 18,
"templateID": 29,
"metaDataGroup": 30,
"rootMediaGroupID": 40,
"mediaGroupStructure": [
String(new Date().getFullYear()),
String(new Date().getMonth() + 1),
String(new Date().getDate())
],
"postSubmissionRedirectBaseUrl": "/1891",
"formToArticleMapping": [{
"from": "form_NAME",
"to": "ArticleHeading"
}, {
"from": "form_SUMMARY",
"to": "ArticleSummary"
}, {
"from": "form_BODY",
"to": "ArticleText"
}, {
"from": "form_METADATA",
"to": "RelatedMetaDataList"
}, {
"value": "2284",
"to": "Extension.BOOKINGID"
}, {
"from": "form_TWITTERUSERNAME",
"to": "Extension.TWITTER"
}, {
"from": "form_FACEBOOKURL",
"to": "Extension.FACEBOOK"
}, {
"from": "form_WEBSITEURL",
"to": "Extension.URL"
}, {
"from": "form_SHOWAVAILABILITY",
"to": "Extension.SHOWAVAILABILITY"
}, {
"from": "form_SHOWDATES",
"to": "Extension.SHOWDATES"
}, {
"from": "form_SHOWLOCATION",
"to": "Extension.SHOWLOCATION"
}, {
"from": "form_SHOWPRICES",
"to": "Extension.SHOWPRICES"
}, {
"from": "form_NOAVAILABILITY",
"to": "Extension.NOAVAILABILITY"
}],
"articleToFormMapping": [{
"from": "ArticleHeading",
"to": "NAME"
}, {
"from": "ArticleSummary",
"to": "SUMMARY"
}, {
"from": "ArticleText",
"to": "BODY"
}, {
"from": "RelatedMetaDataList",
"to": "METADATA"
}, {
"from": "Extension.TWITTER",
"to": "TWITTERUSERNAME"
}, {
"from": "Extension.FACEBOOK",
"to": "FACEBOOKURL"
}, {
"from": "Extension.URL",
"to": "WEBSITEURL"
}, {
"from": "RelatedMetadataList",
"to": "METADATA"
}, {
"from": "Extension.SHOWAVAILABILITY",
"to": "SHOWAVAILABILITY"
}, {
"from": "Extension.SHOWDATES",
"to": "SHOWDATES"
}, {
"from": "Extension.SHOWLOCATION",
"to": "SHOWLOCATION"
}, {
"from": "Extension.SHOWPRICES",
"to": "SHOWPRICES"
}, {
"from": "Extension.NOAVAILABILITY",
"to": "NOAVAILABILITY"
}],
"RelatedMedia": [{
"type": "image",
"files": [{
"fileType": "variant1",
"fieldName": "form_IMAGE"
}],
"formToMediaMapping": [{
"from": "form_NAME",
"to": "Title"
}, {
"from": "form_NAME",
"to": "Description"
}]
}]
}
| Name | Type | Description |
|---|---|---|
| apiKey | String, required | The API Key generated during Installation. We recommend a different API Key, supplying different user credentials, for each instance of Contribute |
| rootArticleID | Integer, required | The fallback parent article for new articles. This can be overridden by users selecting a parent article in the contribute form. Note that all of the standard contribute forms let the user pick a parent article, so this property is rarely used |
| rootArticleIds | Array, required if you want to use the drop-down field on your form | This property provides article IDs and display text to the "where to create this content" drop-down field in the contribute form. Each object in this array has two properties. Only articles secured to user groups the current user is a member of (or those not secured at all) are returned to the form. Note that when Contributing Services the behaviour is different. Because Service articles are always created beneath locations, the rootArticleIds from the Contribute Location configuration End Point are used rather than the settings here |
| rootContributeGroupID | Integer, required | The ID of the website user group allowed to create articles |
| templateID | Integer, required | The ID of the template that articles created by this instance of Contribute should use |
| metaDataGroup | Integer, required | The ID of a metadata group. All the the values of all of the metadata properties in this group will appear as checkboxes on the contribute form |
| rootmediaGroupID | Integer, required | The group under which uploaded media will be created |
| mediaGroupStructure | Array, required | By default media groups will be created with a year-month-day nested structure beneath the root media group |
| postSubmissionRedirectBaseUrl | String, optional | This article ID is used by the redirect actions in some Contribute forms. For example, the Contribute Event form redirects users to an article that uses the event management form |
| formToArticleMapping | Array, required | Each object in this array maps a form field to a parameter of iCM_obj_articleUpdate. See below for more information |
| articleToFormMapping | Array, required | The opposite of the formToArticleMapping. This mapping is used by the update forms so that any changes made dirtectly in iCM are refelected in the forms (rather than the original values held in the workflow engine) |
| RelatedMedia | Array, required | Objects in this array handle the file upload of the contribute form. The properties match those of iCM_obj_mediaUpdate |
Article Mappings
Article mappings map the fields on the create and update forms to iCM article properties understood by the iCM API. Mappings take the form of an array of JSON Objects where "from" is a form field name (in the format form_FIELDNAME) and "to" a parameter of iCM_obj_articleUpdate.
"formToArticleMapping" : [{
"from": "form_NAME",
"to": "ArticleHeading"
},{
"from": "form_INTRO",
"to": "ArticleIntroText"
},{
"from": "form_SUMMARY",
"to": "ArticleSummary"
},{
"from": "form_DETAILS",
"to": "ArticleText"
},{
"from": "form_METADATA",
"to": "RelatedMetaDataList"
},{
"from": "form_WEBSITEURL",
"to": "Extension.URL"
},{
"from": "form_FACEBOOKURL",
"to": "Extension.FACEBOOK"
},{
"from": "form_TWITTERUSERNAME",
"to": "Extension.TWITTER"
},{
"value": "580",
"to": "Extension.BOOKINGID"
}]
The example mapping shows:
- The standard iCM article text areas, including the heading, introductory, summary and body text. Properties like the friendly URL and alternate link text have been excluded
- Metadata values (chosen via a checkbox group field called METADATA), that will be added as related content
- How article extra values are mapped using Extension.FIELDNAME, where FIELDNAME is the name of the field in the target article extras
- Fixed values can also be included by mapping "value" rather than "from". In this example the ID of a form will be added to the article extras BOOKINGID field
The opposite of these mappings need to be added to the articleToFormMapping array.
Media Mappings
The example contribute event configuration includes a single mapping for an uploaded image. Once created the image is related to the contributed article.
"RelatedMedia": [{
// The media type
"type": "image",
// The media files (keyed on component name)
"files": [{
"fileType": "variant1",
"fieldName": "form_IMAGE"
}],
// The mapping from the form fields to the MediaStruct
"formToMediaMapping": [{
"from": "form_NAME",
"to": "Title"
}, {
"from": "form_NAME",
"to": "Description"
}]
}]
Additional media items can be included by adding further file upload fields to the contribute form and duplicating the configuration above.
Each mapping includes the name of an iCM media type definition ("image" in the example above), the name of the component of that media type to create ("variant1" above), the name of the file upload field which will supply the file for the component, and then a mapping to generate the media item's name and description from fields on the form. In this example the media item will have the same title and description as the event article.
A mapping using the older thumbnail/image/large components for images could use the mapping below.
"RelatedMedia": [{
"type": "image",
"files": [{
"fileType": "thumbnail",
"fieldName": "form_IMAGE"
}, {
"fileType": "image",
"fieldName": "form_IMAGE"
}, {
"fileType": "large",
"fieldName": "form_IMAGE"
}],
"formToMediaMapping": [{
"from": "form_NAME",
"to": "Title"
}, {
"from": "form_NAME",
"to": "Description"
}]
}]
Share this page
