Contribution functions#

A contribution form's behavior is authored in Excel. A workbook designer places RW.Contribution.* formulas in the source worksheet; when the campaign generates forms, Reportworq reads the formula metadata and renders the matching editable cells, validation markers, and controls in the contributor's browser form. This page is the reference for those five functions and the placement rules that govern them.

There are five functions, each with a short alias:

Write-back formulas belong in hidden rows#

Before the RW.Contribution functions, note the separate family that actually posts values to the target system when a workbook is processed through data collection. The formula depends on the target:

Keep these write-back formulas in hidden rows or columns. They render as #NAME in the contributor's form, so their rows and columns are hidden by design. Un-hiding them exposes broken-looking cells to the contributor. This is a deliberate layout rule, not a defect.

A contribution campaign does not need these formulas. A campaign's collected values reach the target through its own export, which maps the data model declared in RW.Contribution.Input to the destination. These formulas are what a returned workbook uses when data collection processes it. See Data collection processing.

DBS, DBSW, and DBSS (Planning Analytics)#

The three Planning Analytics write-back functions share one signature and differ only in what they may write.

Signature

DBS(value, "server:cube", element1, element2, …)
DBSW(value, "server:cube", element1, element2, …)
DBSS(value, "server:cube", element1, element2, …)

The three names differ in the cell type each may update.

Behavior

• The element count must match the cube exactly. Too few or too many elements for the cube's dimension list is an error, so a formula written against an older version of a cube fails rather than posting to the wrong intersection.
• An empty value is not skipped. A numeric write with no value posts 0; a string write with no value posts an empty string.
• Consolidated cells are rejected by default. A numeric write to a consolidated intersection fails with "Consolidated input not supported," matching the Planning Analytics Excel add-in. Turning on Proportional Writeback sends the value with the proportional-spread marker instead, so Planning Analytics allocates it across the leaf cells. DBSS is unaffected, because string cells do not consolidate.
• Match the function to the measure. Use DBS or DBSW for numeric measures and DBSS for string measures. A cube that stores a comment or a justification alongside its numbers needs DBSS for that column.

RW.Contribution.Input#

Declares the editable range and its dimensional context. Input cells are created only where every referenced field resolves to a non-blank value, and the formula cell is cleared after evaluation.

Signature

RW.Contribution.Input(inputRange, formName, [allowEditing=TRUE], fieldName, fieldRefOrValue, …)

Reportworq classifies each field reference by its shape: a single-row range is a row axis, a single-column range is a column axis, a single cell or rectangular range is a filter, and a literal is a static value.

Limits

• The inputRange cannot include control cells (cells holding filter, checkbox, or picklist formulas). Overlapping the two corrupts both.
• The formula must not sit on a header row or header column (see Placement rules).
• One data model name must carry one field list. If two forms in a campaign declare the same formName with different fieldName values, the export cannot resolve the model and reports that it is not consistent across forms.

RW.Contribution.Check#

Adds a validation rule for a target cell. The formula cell evaluates to the Boolean result.

Signature

RW.Contribution.Check(targetCell, validationPassed, validationMessage, [validationRequired=FALSE])

Behavior

• A required rule renders as a red/blocking marker and prevents Submit until it passes. A non-required rule renders as a blue/warning marker and is advisory.
• Validation runs on every value change.
• Multiple checks can target one cell.
• Failing messages surface both as cell comments and on the Validations tab of the Details pane.

RW.Contribution.Checkbox#

Creates a checkbox bound to a target cell that stores the checked value.

Signature

RW.Contribution.Checkbox(targetCell, label)

The formula cell shows a [] label placeholder in Excel; the rendered form turns it into an interactive checkbox. The targetCell must be a real cell reference, not a literal.

RW.Contribution.List#

Creates a dropdown bound to a target cell.

Signature

RW.Contribution.List(targetCell, listValuesRange, includesHeader)

Reportworq reads the range, removes duplicates, and stores the option list. With includesHeader=TRUE, the first value is treated as a header, not a choice. The formula cell evaluates to a Picklist: … summary. The targetCell must be a real cell reference.

RW.Contribution.Filter#

Defines a filter control and its value list. The formula cell evaluates to the label text.

Signature

RW.Contribution.Filter([label], [filterValuesRange])

The rendered control has a search box; applying criteria relabels Select All to Select All Selected, multiple criteria can be selected, and the filter applies to input-form rows only.

Signatures at a glance#

Adjacent input function: ANAPLANINPUT#

Beyond the RW.Contribution family, ANAPLANINPUT(inputCell, [tuplePart…]) also marks a cell as a contribution write-back input, flagging its value to post to the matching Anaplan module cell during processing. It is Anaplan-connector-specific and lives in the broader Excel-functions catalog, not the RW.Contribution family.

Workbook design rules#

The function signatures are only half the job. These placement and layout rules are where forms actually break:

• Never place an input, validation, or filter formula on a header row or header column. Do not put a formula in a row that contains column headers, or a column that contains row headers. The axis inference in RW.Contribution.Input depends on the formula sitting inside the data block; on a header line it misroutes or breaks the classification.
• An input range cannot include control cells (filter, checkbox, or picklist formula cells). Overlapping them corrupts both.
• Print Area governs the form's extent. With a Print Area set, only cells inside it appear, and a group that extends past the boundary is truncated, except a chart that spans the boundary is included in full. With no Print Area set, the form is a rectangular block of all non-empty cells, and grouped rows or columns are included whole even if the group contains empty rows.
• Excel data filters exclude hidden rows from the form.
• Merged cells that span a freeze-pane border anchor to the frozen pane.
• Sparklines are supported and update when their linked input cells change.
• Validation surfaces twice: every failing check appears both as a cell comment and on the Validations tab of the Details pane.

Availability#

Every function on this page is available in the current release of Reportworq. The RW.Contribution family was completed over a series of Reportworq 5 updates, RW.Contribution.Filter last, so a workbook authored against an older Reportworq 5 build may not support the full set. If you are targeting an older installation, confirm the version before relying on the newer controls.

Related#

• Author a contribution campaign generates forms from the workbook these formulas live in.
• Fill in and submit a form shows how the rendered controls and markers behave for a contributor.
• Contribution (write-back) overview sets the mental model.
• Data collection processing covers the separate path that runs the hidden write-back formulas.