Prior to v8.0, editing of report XML code had to be done by hand. The introduction of the Report Editor means that most of the code editing scenarios can now be achieved without having to edit code by hand. As such, this document now serves as a reference for those who wish to continue to edit the XML by hand.

Report File Structure

The report definition XML file consists of a number of nodes. The sequence of the nodes, as set out below, must be followed in the report definition file.

  • Header
  • Description
    This node is for defining the optional report description.
  • DataTable
    This node defines the columns available for inclusion in the report from the web part configuration page
  • View Descriptor Nodes
    This node defines the type of report and how a report data will display prior to being configured on the settings page.
    The options include:
    • ViewDescriptor
      The presence of this node tells BrightWork Reporter to render the report as a List Item report.
      OR
    • GanttViewDesciptor
      This presence of this node tells BrightWork Reporter to render the report as a Gantt report.
      OR
    • ChartViewDescriptor
      The presence of this node tells BrightWork Reporter to render the report as a Chart report.
      OR
    • ResourceViewDescriptor
      The presence of this node tells BrightWork Reporter to render the report as a Resource Usage report.
  • QuerySources
    This node defines the sites to be queried if Reporter XML is selected in the Scope menu on the Reporter Settings page - see Configure a Report for more information on the web part configuration page.
  • WebFilters
    This node defines the filters that are used to select the sites to be included in the report based on the site filter Provider.
  • QueryParams
    This node defines the dynamic item filtering options that will be available on the BrightWork Reporter web part UI.
  • WebQueryTemplates
    This node allows you to specify a site query using:
    • SharePoint's SPSiteDataQuery
    • A web query template provider to determine the sites to be retrieved in the query. These web query templates can be used in conjunction with the ListQueryTemplates below.
  • ListQueryTemplates
    This node defines the lists/libraries to be included in the query. It can also include a ListCollectionProvider that enables the List of Lists.
  • ProjectMetrics
    This node defines the Project Metrics list columns that are to be joined to Project Statements in reports.
  • Footer

Header and Footer

Every report must have:

<?xml version="1.0" encoding="utf-16"?>

<ListItemQuery xmlns="http://schemas.brightwork.com/ListItemReportManifest">

as a header and

</ListItemQuery>

as a footer.

Description

The Description node defines the optional text that is displayed in the report footer.

Data Table Node

The Data Table node defines the columns available for selection from the BrightWork Reporter configuration page.

Opening and closing tags

<DataTable>
</DataTable>

Column Types

You must detail the SharePoint column type, of the columns to be included in the Data Table, and certain attributes specific to the column type in question.

The available column types include:

Column Type SharePoint List Column Type
<BooleanColumn Yes/No
<ChoiceColumn Choice
<CurrencyColumn Currency
<DateTimeColumn Date and Time
<IconColumn Hyperlink or Picture
<LookupColumn Lookup
<MetricIndicatorStatusColumn Integer Mapping
<ModerationStatusColumn Integer Mapping
<NoteColumn Multiple lines of text
<NumberColumn Number
<TextColumn Single line of text
<UrlColumn Hyperlink or Picture
<UserColumn Person or Group
<WorkflowStatusColumn Integer Mapping

Common Attributes

This section describes the attributes that are common to all column types.

name=""

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

caption=""

The column title that will appear on the configuration page and in the column header in the report.

Boolean Column

This section describes the attributes specific to <BooleanColumn.

Example: <BooleanColumn name="CompletedFlag" caption="Completed Flag" />

<BooleanColumn

name=""

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

caption=""

The column title that will appear on the configuration page and in the column header in the report.

expression=""

Allows you to insert a data column expression, for example:

<BooleanColumn name="OverDueFlag" caption="Overdue Flag" defaultValue="0" expression="IIF(#Today#>[DueDate],1,0)" />

This expression would return a Boolean value of true (1) for any overdue items. This would be displayed as a Yes in the report and No if the result was false (0).

Please see http://msdn2.microsoft.com/en-us/library/system.data.datacolumn.expression(vs.71).aspx for more information from Microsoft on data column expressions.

defaultValue=""/>

If no value is returned from the query, this attribute allows you to specify a default value.

Allowed values are: 0, 1, true or false.

Choice Column

This section describes the attributes specific to <ChoiceColumn

<ChoiceColumn

name=""

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

caption=""

The column title that will appear on the configuration page and in the column header in the report.

allowMulti=""

Allows you to specify if this column will be multi-value.

  • true
  • false

defaultValue=""/>

If no value is returned from the query, this attribute allows you to specify a default value.

Currency Column

This section describes the attributes specific to <CurrencyColumn.

<CurrencyColumn

name

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

caption

The column title that will appear on the configuration page and in the column header in the report.

currencyLocaleId

Enter the locale of the desired currency symbol.

numberOfDecimals

This attribute is used to specify the number of decimal places to be used.

Available values include:

  • Automatic
  • TwoDecimals
  • ThreeDecimals
  • FourDecimals
  • FiveDecimals
  • NoDecimal

expression

Allows you to insert a data column expression. An example of such an expression would be:

<CurrencyColumn name="OverduePenalty" caption="Overdue Penalty" defaultValue="0" expression="IIF(#Today#<DateDue,10000,0)" numberOfDecimals="NoDecimal" />

This expression would return a penalty of $10,000 (assuming dollars) for any overdue items.

Please see http://msdn2.microsoft.com/en-us/library/system.data.datacolumn.expression(vs.71).aspx for more information from Microsoft on data column expressions.

defaultValue=""/>

If no value is returned from the query, this attribute allows you to specify a default value.

Date Time Column

This section describes the attributes specific to <DateTimeColumn

<DateTimeColumn

name=""

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

caption=""

The column title that will appear on the configuration page and in the column header in the report.

displayFormat =" "

Optional attribute used to specify the display format of the date.

For example: displayFormat=???MM/DD/YYYY'.

See Custom Date and Time Display Formats for more information.

expression=""/>

Allows you to insert a data column expression. An example of such an expression would be:

<DateTimeColumn name="OverdueDate" caption="Overdue Date" expression = "IIF(#Today#<DateDue, DateDue,'')" />

This expression would return the Date Due value of any overdue items.

Please see http://msdn2.microsoft.com/en-us/library/system.data.datacolumn.expression(VS.71).aspx for more information from Microsoft on data column expressions.

Icon Column

This section describes the attributes specific to <IconColumn

<IconColumn

name=""

The name SharePoint uses to identify the column.

Supported Icon columns include:

  • PriorityIcon

  • StatusIcon

  • StatusIndicatorIcon

  • PercentCompleteIcon

  • PercentCompleteIndicatorIcon

caption=""

The column title that will appear on the configuration page and in the column header in the report.

viewHeadIcon=""

Allows you to specify an icon to display in the column heading in the report.

viewHeadTitle=""/>

Allows you to specify the Title to display in the column heading in the report.

Lookup Column

This section describes the attributes specific to <LookupColumn.

<LookupColumn

name=""

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

allowMulti=""

Allows you to specify if this column will be multi-value.

  • true
  • false

caption=""/>

The column title that will appear on the configuration page and in the column header in the report.

Note Column

This section describes the attributes specific to <NoteColumn.

<NoteColumn

name=""

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

caption=""

The column title that will appear on the configuration page and in the column header in the report.

displayAsRichText=""/>

This setting allows you to display the contents of a rich text or enhanced rich text Multi-line text field as is. Available options include:

  • true
  • false

Number Column

This section describes the attributes specific to <NumberColumn

<NumberColumn

name=""

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

caption=""

The column title that will appear on the configuration page and in the column header in the report.

displayFormat=""

Used to specify the format of numeric value being displayed.

The available types include:

  • p (or %) Percent format

numberOfDecimals=""

This attribute is used to specify the number of decimal places to be used.

Available values include:

  • Automatic
  • TwoDecimals
  • ThreeDecimals
  • FourDecimals
  • FiveDecimals
  • NoDecimal

expression=""

Allows you to insert a data column expression.

An example of such an expression would be:

<NumberColumn name="OverNumberAnomalies" caption="Number of Extra Anomalies" defaultValue="0" expression= "IIF(ActualNumberOfAnomalies>PlannedNumberOfAnomalies, ActualNumberOfAnomalies - PlannedNumberOfAnomalies, 0)" />

This expression compares two number columns, 'PlannedNumberOfAnomalies' and 'ActualNumberOfAnomalies'. It determines if the number of actual anomalies exceeds the number of planned anomalies. If it does, the difference is displayed, otherwise 0 is displayed.

Please see http://msdn2.microsoft.com/en-us/library/system.data.datacolumn.expression(vs.71).aspx for more information from Microsoft on data column expressions.

defaultValue=""/>

If no value is returned from the query, this attribute allows you to specify a default value.

Text Column

This section describes the attributes specific to <TextColumn

<NumberColumn

name=""

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

caption=""

The column title that will appear on the configuration page and in the column header in the report.

expression=""

Allows you to insert a data column expression.

An example of such an expression would be:

<TextColumn name="OverDueGrouping" caption="Overdue" defaultValue="On Target" expression="IIF(#Today#>DateDue, 'Overdue','On Target')" />

This expression would return a text value of 'Overdue' for any overdue items and 'On Target' for others.

Please see http://msdn2.microsoft.com/en-us/library/system.data.datacolumn.expression(vs.71).aspx for more information from Microsoft on data column expressions.

defaultValue=""/>

If no value is returned from the query, this attribute allows you to specify a default value.

URL Column

This section describes the attributes specific to <UrlColumn

<UrlColumn

name=""

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

caption=""

The column title that will appear on the configuration page and in the column header in the report.

urlFormat=""/>

Allows you to specify the format of the URL. Available values include:

  • Hyperlink
    For standard URL references - this is the default value
  • Image
    Where the URL is pointing at an image

User Column

This section describes the attributes specific to <UserColumn

<UserColumn

name=""

The name SharePoint uses to identify the column. Normally this is the name that appears on the list, minus any spaces. For example, if the column was called 'Issue Type', the SharePoint column name should be 'IssueType'. See Tip 1 - How to identify the real SharePoint column name for more information.

allowMulti=""

Allows you to specify if this column will be multi-value.

  • true
  • false

caption=""/>

The column title that will appear on the configuration page and in the column header in the report.

View Descriptor Nodes

The View Descriptor node defines how the report appears on a web part page.

There is a corresponding view descriptor node for each type of BrightWork Reporter report:

  • Chart Reports:
    ChartViewDescriptor

  • Gantt Reports:
    GanttViewDescriptor

  • List Item Reports:
    ViewDescriptor

  • Resource Usage Reports:
    ResourceViewReports

Chart Reports

The presence of the ChartViewDescriptor node tells BrightWork Reporter that this is to be a chart type report.
This table below describes the nodes and values specific to the Chart View Descriptor.

<ChartViewDescriptor>

<Chart chartProvider=" "

Specify the chart provider:

  • Custom
  • MicrosoftChart

chartType=" "

Specify the chart type:

  • Custom
    • Bar
  • MicrosoftChart
    • Area
    • Bar
    • Column
    • Doughnut
    • Pie
    • Line
    • Spline
    • StackedArea
    • StackedArea100
    • StackedBar
    • StackedBar100
    • StackedColumn
    • StackedColumn100
    • StepLine

themeName=" "

Specify a theme for the chart:

  • default
  • borg
  • bright1
  • bright2
  • bluescale
  • greyscale
  • primary
  • trafficlight

width=""

Specify the width (in pixels) of the chart.

height="">

Specify the height (in pixels) of the chart.

<Title alignment=" "

Specify an alignment for the title:

  • Center
  • Left
  • Right

location=""

Specify a location for the title:

  • Top
  • Bottom

title=""

Specify the title.

visible=""/>

Set whether or not the title is visible:

  • true
  • false

<Legend alignment=" "

Specify an alignment for the legend:

  • Center
  • Left
  • Right

location=" "

Specify a location for the legend:

  • Top
  • Bottom

visible=" "/>

Set whether or not the legend is visible:

  • true
  • false

<DataSeries>
<Labels visible="" />
</DataSeries>

Set whether or not data labels are visible:

  • true
  • false

</Chart>

Closing tag

<DataSeriesBinding>

Opening tag

This section is where the columns that make up the graph are detailed.

<XField

fieldName=" "

Specify the column to use on the X-axis.

sortBy=""

Specify the sort direction for the X-axis:

  • Ascending
  • Descending

groupBy=""

Specify whether or not to enable grouping/aggregation of values:

  • true
  • false

excludeZeroYValues="">

Specify whether or not to exclude items with a Y-column value of zero.

  • false
  • true

<YFields>

<YField

For most chart types you can include up to 4 Y-Axis columns. The exception are for Pie and Doughnut.

showGroupByCount=""

Specify whether or not to display the number of items in the X-Axis column.

  • false
  • true

fieldName=" "

Specify a number column to graph on the Y-Axis.

formulaType=" "/>

Specify a formula to use against the data:

  • None

  • Average

  • Maximum

  • Minimum

  • Sum

  • StandardDeviation

  • Variance

</YFields>

</DataSeriesBinding>

</ChartViewDescriptor>

Gantt Reports

The presence of the GanttViewDescriptor node tells BrightWork Reporter that this is a Gantt report.

The table below describes the nodes and values specific to the Gantt View Descriptor.

<GanttViewDescriptor version="2">

<Grouping>

Set default Grouping for the report.

<GroupBy

You can have from zero to four GroupBy nodes which allows you up to four levels of grouping

name=""

Specify the column you want the items returned to be grouped by and whether you want the grouping to be collapsed or expanded.

The GroupBy name attribute must equate to a column name in the data table node.

expanded=""

Specify whether or not you want the groups to be expanded or not.

  • false (default)
    Equivalent to Collapsed on the Reporter Settings page.
  • true

direction=""/>

Specify the direction to sort the groups.

  • Ascending
  • Descending

</Grouping>

<Sorting>

Set default Sorting for the report.

<SortBy

You can have from zero to four SortBy nodes which allows you up to four levels of sorting

name=""

Specify the column you want to use to sort the items returned and the direction you want them to be sorted.

The SortBy name attribute must equate to a column name in the data table node

direction =""/>

Specify the sort direction.

  • Ascending (default)
  • Descending

</Sorting>

<LinkFieldName name=""

Specify the column the column you want to use to link to the individual list items.

anchorTarget="" />

Specify how you want the links in reports to behave.

The options include:

  • _dialog
    Links will open list items in the pop-up dialog introduced in SharePoint 2010.
  • _self
    Links will open list items in the same browser window as the report (equivalent to selecting Never on the Reporter Settings page).
  • _blank
    List items will open in a new browser window every time (equivalent to selecting Each Time on the Reporter Settings page).
  • _bwWindow
    All list items will open in the same separate browser window (equivalent to selecting Once Only on the Reporter Settings page).

<ViewFields>

Specify the columns you want to include in the list item area of the report. The order the columns are added sets the left to right order in the report.

<Field name=""

Enter the column name.

width="" />

Specify a width between 20 and 600 pixels for the column.

</ViewFields>

<TimeWindow

basedOn=""

Specify the Time Window that the Gantt should report on.

The options include:

  • AllData
    This shows all items returned from the earliest date found to the latest date found.
  • Today
    This shows the items returned according to the remaining Time Window speciations.

backUnits=""

Specify the back units to use in setting the Time Window.

The options include:

  • Days
  • Weeks
  • Months

backValue=""

Specify the number of units to look back.

forwardUnits=""

Specify the forward units to use in setting the Time Window.

The options include:

  • Days
  • Weeks
  • Months

forwardValue=""

Specify the number of units to look forward.

/>

Closing tag for Time Window section.

<DataBinding

Specify the columns to use in the Time Window section of the Gantt chart.

startDateFieldName=""

Specify the Date Time column to use as the Start Date

finishDateFieldName=""

Specify the Date Time column to use as the End Date

percentCompleteFieldName=""

Specify the NumberColumn (that has a display format of p or includes % in the display format in the DataTable) to used as the % complete element of the Gantt display

milestoneFlagFieldName=""

Specify a column to use as the Milestone Flag.

taskLabelFieldName=""

Specify the column that will provide data to the Task bar label.

summaryTaskLabelFieldName=""

Specify the column that will provide data to the Summary Task bar label.

milestoneLabelFieldName=""

Specify the column that will provide data to the Milestone label.

excludeItemsWithNoDates="false"

Specify whether or not to exclude items with no start and finish dates.

  • false
  • true

/>

Closing tag for Data Binding section.

<TimeArea width="" />

Specify a width (between 20 and 100000 pixels) for the time window.

<DateScale panFactor="" />

Specify a value (between 50 and 100) for the pan factor percentage.

<ViewSettings

themeName="default"

Specify a theme for the Gantt.

The options include:

  • default
  • bw
    Black and White
  • excel

rowHeight=""

usePaging=""

Specify whether or not to activate paging.

  • true
  • false

rowsPerPage="20" />

Specify the number of rows to show per page.

</GanttViewDescriptor>

List Item Reports

The presence of the ViewDescriptor node tells BrightWork Reporter that this is to be a list item report.

The table below describes the nodes and values specific to the ViewDescriptor node.

<ViewDescriptor>

<ViewFields>

This is where you specify the columns to include in the report.

<Field name=""/>

The FieldName attribute must equate to a column name in the data table node.

</ViewFields>

<LinkFieldName name=""

Specify the column that will contain the URL link back to the list item, generally this will be the Title column, but it does not have to be.

The LinkFieldName name attribute must equate to a column name in the data table node.

You should choose this column carefully, as this may be the only link column in the report.

Only certain column types are supported:

  • Currency
  • Date Time
  • Number
  • Text
  • Choice single value
  • Yes/No (Boolean )

anchorTarget="" />

Specify how you want the links in reports to behave.

The options include:

  • _dialog
    Links will open list items in the pop-up dialog introduced in SharePoint 2010.
  • _self
    Links will open list items in the same browser window as the report (equivalent to selecting Never on the Reporter Settings page).
  • _blank
    List items will open in a new browser window every time (equivalent to selecting Each Time on the Reporter Settings page).
  • _bwWindow
    All list items will open in the same separate browser window (equivalent to selecting Once Only on the Reporter Settings page).

<Sorting>

Set default Sorting for the report.

<SortBy

You can have from zero to four SortBy nodes which allows you up to four levels of sorting

name=""

Specify the column you want to use to sort the items returned and the direction you want them to be sorted.

The SortBy name attribute must equate to a column name in the data table node

direction =""/>

  • Ascending (default)
  • Descending

</Sorting>

<Grouping>

Set default Grouping for the report.

<GroupBy

You can have from zero to four GroupBy nodes which allows you up to four levels of grouping

name=""

Specify the column you want the items returned to be grouped by and whether you want the grouping to be collapsed or expanded.

The GroupBy name attribute must equate to a column name in the data table node.

expanded=""

  • false (default)
  • true

direction=""/>

Specify the direction to sort the groups.

  • Ascending
  • Descending

</Grouping>

<Aggregations

Defines the aggregates (totals) to be included in the report.

displayCaptions="">

Specify whether or not to enable captions for the totals.

  • false
  • true

<Aggregate

name=??????

The Aggregate name attribute must equate to a column name in the data table node

type=??????/>

This describes the type of aggregate to compute. The function type must be in all capitals.

Type

Description

Column Type Supported

Avg

Average
Calculates the average value for a column.

Number, Decimal, Currency

Count

Count
Counts the number of items in a column.

All

Max

Maximum
Returns the item with the highest value.

Number, Decimal, Currency, Date/Time

Min

Minimum
Returns the item with the lowest value.

Number, Decimal, Currency, Date/Time

Stdv

Standard Deviation
Measures how widely values are dispersed from an average value (a mean).

Number, Decimal, Currency

Sum

SUM
Adds the items in a column...

Number, Decimal, Currency

Var

Variance
Measures the statistical variance of all values in the column.

Number, Decimal, Currency

</Aggregations>

</ViewDescriptor>

Resource Usage Reports

The presence of the ResourceUsageViewDescriptor node tells BrightWork Reporter that this is to be a resource-usage report.

This table below describes the nodes and values specific to the Resource-Usage View Descriptor.

<ResourceUsageViewDescriptor>

<ViewSettings overAllocationHighlight =""

Specify whether to highlight when a resource had been over-allocated.

  • true
  • false

excludeItemsWithNoAllocations =""

Specify whether to exclude items with no allocation data.

  • true
  • false

overAllocationWarningValue=""

Specify a unit value for the selected grouping(s). This will divide the value entered into the work column by this number to determine if anyone in the grouping is over-allocated.

overAllocationHighlightColor =""/>

This feature is not currently supported.

<DataBinding

startDateFieldName=""

Specify the date time column to use as the start date for the displayed data.

finishDateFieldName=""

Specify the date time column to use as the end date for the displayed data.

workFieldName=""

Specify the number column to use as the effort for the displayed data.
This should only be a column where work effort is entered in hours.

showAllocationAsPercentage=" " />

  • true
  • false

<CalendarSettings customWorkingHoursPerDay=""/>

<TimeWindow basedOn=" "

Specify the Time Window to use when rendering the report.

  • AllData
  • Today

backUnits=" "

If Today is the specified Time Window, specify the back unit to use.

  • Days
  • Weeks
  • Months

backValue="0"

If Today is the specified Time Window, specify the number of backUnits to look back

forwardUnits=" "

If Today is the specified Time Window, specify the forward unit to use.

  • Days
  • Weeks
  • Months

forwardValue="" />

If Today is the specified Time Window, specify the number of forwardUnits to look forward

<Timescale>

<Major units=" " />

Specify the top timescale

  • Weeks
  • Months
  • Quarters
  • Years

<Minor units=" " />

Specify the bottom timescale

  • Days
  • Weeks
  • Months
  • Quarters

<NonWorkingTime display=" " />

Specify whether to include days designated as non-working in the displayed report.

  • true
  • false

</Timescale>

<ViewFields>

<Field name=" " />

Specify the columns to include in the report.

</ViewFields>

<Sorting>

You can sort by up to four columns

<SortBy name=" "

Specify the column(s) you want to use to sort the items returned.

The SortBy name attribute must equate to a column name in the data table node. You can have from zero to four SortBy nodes which allows you up to four levels of sorting.

direction=" " />

Specify the direction to sort that data in:

  • Ascending
  • Descending

</Sorting>

<Grouping>

You can group by up to four columns

<GroupBy name=""

Specify the column you want the items returned to be grouped by and whether you want the grouping to be collapsed or expanded.

The GroupBy name attribute must equate to a column name in the data table node. You can have from zero to four GroupBy nodes which allows you up to four levels of grouping

expanded=" "

Specify whether or not the groups should be collapsed or expanded

Selecting Collapsed in any group means that all subsequent groups below that group will also be collapsed.

  • true
  • false

direction=" " />

Specify the direction to sort the groups.

  • Ascending
  • Descending

</Grouping>

<LinkFieldName name=""

Specify the column that will contain the URL link back to the list item, generally this will be the Title column, but it does not have to be.

The LinkFieldName name attribute must equate to a column name in the data table node.

You should choose this column carefully, as this may be the only link column in the report.

Only certain column types are supported:

  • Currency
  • Date Time
  • Number
  • Text
  • Choice single value
  • Yes/No (Boolean )

anchorTarget="" />

Specify how you want the links in reports to behave.

The options include:

  • _dialog
    Links will open list items in the pop-up dialog introduced in SharePoint 2010.
  • _self
    Links will open list items in the same browser window as the report (equivalent to selecting Never on the Reporter Settings page).
  • _blank
    List items will open in a new browser window every time (equivalent to selecting Each Time on the Reporter Settings page).
  • _bwWindow
    All list items will open in the same separate browser window (equivalent to selecting Once Only on the Reporter Settings page).

</ResourceUsageViewDescriptor>

QuerySources Node

The optional QuerySources node details the sites that are to be queried if Reporter XML is selected in the Scope menu on the configuration page; in effect, this allows you to specify the sites to be queried independent of where the report is being rendered. This can be very useful if you want to query off multiple site collection or specific sites located in various locations in a site collection hierarchy.

<QuerySources>

<QuerySource
href="https://help.brightwork.com/15.5/"

Specify the URL of the site to be included in the report. There can be any number of these.

recursive=""/>

Specify whether or not to include subsites in the query.

  • true = Include subsites
  • false = Exclude subsites

<QuerySource
Provider

A Query Source Provider is a piece of custom code written to select sites for reporting on a custom basis. As there are no providers included in the base product, creating a Query Source Provider is beyond the scope of this document.

See below for an example of what a Query Source Provider might look like.

<QuerySourceProvider assembly="BrightWork, Version=12.0.0.0, Culture=neutral, PublicKeyToken=bdb4a6220fe9433c" class="BrightWork.Reporter.Providers.ImmediateSubWebsQuerySourceProvider"></QuerySourceProvider>

</QuerySources>

WebFilters

Site filters (WebFilters in the XML) are a way of excluding certain sites from being included in the report. Site filters can be switched on and off from the BrightWork Reporter configuration page.

There are three types of site filter:

  • Provided Filters

  • Project Filters

  • Custom Site Filters

Provided Filters

Two site filters are provided in BrightWork:

  • Exclude Completed projects
  • Exclude Archived projects (triggers if Exclude from Reports is selected in the Project Statement)

These providers exclude projects sites depending on whether the Completed Flag and/or Archive flag is set in the Project Statement item for the project.

The code for these site filters is displayed below.

<WebFilters>
<WebFilterProvider id="1" displayName="Exclude Completed projects" enabled="true" assembly="BrightWork, Version=12.0.0.0, Culture=neutral, PublicKeyToken=bdb4a6220fe9433c" class="BrightWork.Reporter.Providers.ExcludeCompletedProjectsWebFilter">
<Property name="IfNotProjectWeb">false</Property>
<Property name="IfNoProjectSummary">false</Property>
</WebFilterProvider>
<WebFilterProvider id="2" displayName="Exclude Archived projects" enabled="true" assembly="BrightWork, Version=12.0.0.0, Culture=neutral, PublicKeyToken=bdb4a6220fe9433c" class="BrightWork.Reporter.Providers.ExcludeArchivedProjectsWebFilter">
<Property name="IfNotProjectWeb">false</Property>
<Property name="IfNoProjectSummary">false</Property>
</WebFilterProvider>
</WebFilters>

Project Filters

You can also create a site filter using Query CAML. The CAML is run against the Project Statement list.

See below for a sample project filter. This example would only return items from projects that had the logged in user specified as Project Manager in the Project Statement list.

<WebFilterProvider id="3" enabled="true" assembly="BrightWork, Version=12.0.0.0, Culture=neutral, PublicKeyToken=bdb4a6220fe9433c" class="BrightWork.Reporter.Providers.CamlQueryProjectSiteFilter" displayName="Project Manager">

<Property name="IfNotProjectWeb">false</Property>

<Property name="IfNoProjectSummary">false</Property>

<Property name="QueryCaml"><Where>

<Eq>

<FieldRef Name="Owner" LookupId="TRUE" />

<Value Type="int">[CurrentUser]</Value>

</Eq>

</Where></Property>

</WebFilterProvider>

Custom Site Filters

Custom site filters allow you to call a provider you have created yourself. Creating such providers is beyond the scope of this document.

QueryParams Node

The optional QueryParams node is for defining any filtering options to be available in the BrightWork Reporter UI.

There are five types of filter:

  • DateTime
  • User
  • Text
  • Boolean
  • Choice

Non-choice QueryParams

Non-choice QueryParams are where the user enters a value into a text box and/or selects or specifies a date.

<QueryParams

requireUserInput="">

Specifying true means that the web part will only render if the user clicks Apply Filter.

The default value is false. If you leave this attribute out the default value will apply.

  • false
  • true

<BooleanParam

or

<DateTimeParam

or

<NumberParam

or

<UserParam

or

<TextParam

The available types of non-choice QueryParam include:

  • Boolean
    Yes or No/true or false. Used to query against Boolean fields. For example, show me Issues with Completed Flag of No.
  • Date/Time
    Allows you to specify the date to filter the report data. For example, show me Issues with a Date Due greater than Today.
  • Number
    Allows you to specify numeric filtering. For example, show me Issues with an Expected Cost greater than $1,000.
  • User
    Allows you filter by user name. For example, show me Issues where I select the Issue owner.
  • Text
    Allows you to filter by text value. For example, show me Issues when the Title contains 'Critical'.

name=""

The name of the parameter you will be using that will be replaced in the CAML in the List or Web QueryTemplates nodes.

This is equivalent to the Named Attribute element mentioned in Using CAML with Dynamic BrightWork Reporter Filters.

caption=""

The caption you want to use in the web part UI.

showAsPercentage=""

For the NumberParam, specify if the number should be displayed as a percentage value:

  • true
  • false

defaultValue=""/>

The default value you would like the filter to have, for example if the data type was User the recommended default value would be [me].

If the data type was Date the recommended default value is [today]; you can also use expressions like [today +7] and [today -7].

Hard-coding of date values is supported and the format is:

YYYY-MM-DDTHH:MM:SSZ e.g. 2003-6-10T12:00:00Z

</QueryParams>

Choice QueryParams

The ChoiceParam option allows the report user to filter a report by selecting a value that appears in a drop-down menu, For example, selecting a user in the My Work report.

The source of the list of filter values in the drop-down menu depends on the sourceType specified.

There are five sourceTypes:

XmlInline

This sourceType allows you to hardcode the filter values in the Report Definition file.

<QueryParams

requireUserInput="">

Specifying true means that the web part will only render if the user clicks Apply Filter.

The default value is false. If you leave this attribute out the default value will apply.

  • false
  • true

<ChoiceParam

name=""

The name of the parameter you will be using that will be replaced in the CAML in the QueryTemplates node.

caption=""

The caption you want to give the filter in the web part UI.

defaultValue="">

The default value you would like the filter to have.

<Values

sourceType=""

or

sourceType="XmlInLine"

This is the default sourceType (if none is specified it will be used).

<Value></Value>

Specify the values that will be in the drop down menu in the report filter.

For example, in this sample two choices will appear, 'Value 1' and 'Value 2'.

<Value>Value 1</Value>
<Value>Value 2</Value>

</Values>

</ChoiceParam>

</QueryParams>

ListInWeb

This sourceType allows you to specify that the filter values be pulled from a named column in a named list. The list must exist on the same site as the instance of the BrightWork Reporter web part.

<QueryParams

requireUserInput="">

Specifying true means that the web part will only render if the user clicks Apply Filter.

The default value is false. If you leave this attribute out the default value will apply.

  • false
  • true

<ChoiceParam

name=""

The name of the parameter you will be using that will be replaced in the CAML in the QueryTemplates node.

caption=""

The caption you want to give the filter in the web part UI.

defaultValue="">

The default value you would like the filter to have.

<Values

sourceType="ListInWeb"

source=""

Specify the name of the list in the current site containing the items from which you want to pull the values. For example, source="Tasks"

fieldName="">

Specify the choice column name in the List from which you want to pull the values. For example, fieldName="Title".

</Values>

</ChoiceParam>

</QueryParams>

ListAtPath

This sourceType allows you to specify that the filter values be pulled from a named column in a named list. The list is specified using a server-relative URL. The advantage of this option is that multiple reports can all refer to a common list of values maintained in one place.

<QueryParams

requireUserInput="">

Specifying true means that the web part will only render if the user clicks Apply Filter.

The default value is false. If you leave this attribute out the default value will apply.

  • false
  • true

<ChoiceParam

name=""

The name of the parameter you will be using that will be replaced in the CAML in the List or Web QueryTemplates node.

caption=""

The caption you want to give the filter in the web part UI.

defaultValue="">

The default value you would like the filter to have.

<Values

sourceType="ListAtPath"

source=""

Specify the server-relative URL of the list. For example, source="/sites/ITProjects/Project1/Lists/Project Tasks/AllItems.aspx"

fieldName="">

Specify the choice column name that you want to pull the values from in the list specified. For example, fieldName="Status".

</Values>

</ChoiceParam>

</QueryParams>

XmlInLib

This sourceType allows you to specify that the filter values are in an XML file stored in a document library on the server. The XML file is identified by a server-relative URL.

<QueryParams

requireUserInput="true">

Specifying true means that the web part will only render if the user clicks Apply Filter.

The default value is false. If you leave this attribute out the default value will apply.

  • false
  • true

<ChoiceParam

name=""

The name of the parameter you will be using that will be replaced in the CAML in the QueryTemplates node.

caption=""

The caption you want to give the filter in the web part UI.

defaultValue="">

The default value you would like the filter to have.

<Values

sourceType="XmlInLib"

This sourceType allows you to specify an XML file in a document library as the source of the list of values. The XML file is addressed as a relative address.

source=""

Specify the server-relative URL of the XML file. For example, source="/sites/ITProjects/Projects1/Documents/Choice.xml"

Please refer to the XmlInLib and XmlAtPath Source File section below for more information on this XML files layout.

</Values>

</ChoiceParam>

</QueryParams>

XmlAtPath

This sourceType allows you to specify that the filter values are pulled from an XML file stored in a virtual directory on the server. The XML file is identified by a server-relative URL.

<QueryParams

requireUserInput="true">

Specifying true means that the web part will only render if the user clicks Apply Filter.

The default value is false. If you leave this attribute out the default value will apply.

  • false
  • true

<ChoiceParam

name=""

The name of the parameter you will be using that will be replaced in the CAML in the List or Web QueryTemplates node.

caption=""

The caption you want to give the filter in the web part UI.

defaultValue="">

The default value you would like the filter to have.

<Values

sourceType="XmlAtPath"

This sourceType allows you to specify an XML file that is located on the server. The XML file is addressed as a relative address.

source=""

Specify the URL of the XML file.

For example: source="/_layouts/15/brightwork/custom/Choice.xml" if the XML file is placed in a new folder on the BrightWork Reporter server at:
<Drive>:\Program Files\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\LAYOUTS\BrightWork\custom

Please refer to the XmlInLib and XmlAtPath Source File section below for more information on this XML files layout.

</Values>

</ChoiceParam>

</QueryParams>

XmlInLib and XmlAtPath Source File

The source file for XmlInLib and XmlAtPath type Choice QueryParams is a simple XML file.

<?xml version="1.0" encoding="utf-8" ?>
<Values>
<Value>Not Started</Value>
<Value>In Progress</Value>
<Value>Completed</Value>
<Value>Deferred</Value>
<Value>Waiting on someone else</Value>
</Values>

WebQueryTemplates Node

The WebQueryTemplates node describes a query performed across multiple lists, which may be located in multiple sites within the same Site Collection.

<WebQueryTemplates>

<WebQueryTemplate>

If you have a WebQueryTemplates node, you must have at least one WebQueryTemplate node. You can have as many WebQueryTemplate nodes as you see fit.

<QueryFields>

The columns in the list that are to be included in the query.

<Field name=""

Specify the internal column name of a column that you want to include in the query.

Unless you use alternate mapping by using the columnName attribute, this is the name you must use in the DataTable.

columnName=""

This is an optional attribute that maps the column named in <Field name=?????? to a different DataTable column name. The columnName is the name attribute you use in the DataTable.

Please see Datatable Column Mapping Scenarios for an explanation of the scenarios where you would need to do this.

nullable=""/>

nullable allows you to flag that certain fields may not exist in all the lists being queried.

Allowed values are: 0, 1, true or false.

</QueryFields>

<QueryCaml> </QueryCaml>

Please refer to the Working with Query CAML section for more information on using CAML in BrightWork Reporter.

<ListsCaml>

Specify the lists that are to be queried.

<Lists ServerTemplate="">

OR

<Lists BaseType="">

Specify the lists to include in the query.

ServerTemplate

Limits the query to lists of the specified list type. Please see List Types for a full list of the list types.

OR

BaseType

Limits the query to lists of the specified base type.

For example: <Lists BaseType="1"/>

The available types include:

  • 0
    Generic list
  • 1
    Document library
  • 3
    Discussion forum
  • 4
    Vote or Survey
  • 5
    Issues list

<WithIndex

The WithIndex tag is an optional child of the Lists node, when present, the query will be limited to lists with indexed fields. The WithIndex element has three required attributes: FieldId, Value, and Type.

FieldId="???

The FieldId of the column on which you want to perform the comparison.

Type="Text???

The Type attribute must be set to Text

Value="???/>

The value you want to compare the column to.

In the following example, the query considers only lists that contain items whose specified column is set to the text value ???Complete???.

<WithIndex FieldId="D4819257-6B69-41F1-82C8-A91615BFF500" Type="Text" Value="Complete" />

</Lists>

</ListsCaml>

<RowLimit> </RowLimit>

Specify a limit on the number of rows (items) returned by the QueryCaml.

For example, <RowLimit>5</RowLimit> returns the first 5 items returned by the CAML query.

<QueryScope></QueryScope>

The QueryScope node specifies whether the scope of the query. Valid values include:

  • Recursive
    This will query the current site and all its subsites
  • SiteCollection
    This will query the entire site collection of the current site

</WebQueryTemplate>

</WebQueryTemplates>

ListQueryTemplates Node

The ListQueryTemplates node defines the lists that will be included in the report. You can have a ListQueryTemplate node for every list type or list name you wish to include. Alternatively, you can use the DefaultListTemplate or DefaultLibraryTemplate, which would cover all the lists and libraries in the scope of the report.

You must specify the columns to be included for each list type in the QueryFields node. You can also include CAML queries to refine the data returned from the lists to the report.

<ListQueryTemplates>

<ListCollectionProvider assembly="
BrightWork, Version=15.0.0.0, Culture=neutral, PublicKeyToken=bdb4a6220fe9433c"
class="BrightWork.Reporter.
Providers.ListsFromListCollectionProvider">

List Collection Provider statement.

This is for the List of Lists.

<Property name="ListName"> </Property>

The List of Lists name.

<Property name="ProcessWebIfNoList">true</Property>

Specify whether or not the report should query the site if no list matching the named List of Lists is found.

  • true
  • false

</ListCollectionProvider>

<ListQueryTemplate>

You must have at least one ListQueryTemplate node. You can have as many ListQueryTemplate nodes as you need.

A ListQueryTemplate can be one of four different types:

  • ListTypeFilter
  • ListNameFilter
  • DefaultLibraryTemplate
  • DefaultListTemplate

<ListTypeFilter listType=""/>

OR

<ListNameFilter listName=""/>

OR

<DefaultLibraryTemplate/>

OR

<DefaultListTemplate/>

<ListTypeFilter

Enter the List Type number(s). You can refer to the lists to be reported upon by their List Type, which is an integer that represents the list type of the list.

Please see List Types for a full list of the list types.

OR

<ListNameFilter

Alternatively, use a list name to return data from all the lists with the name specified. Enter the List Name.

For example, to report on all Lists called Tasks enter:
<ListNameFilter listName="Tasks"/>

OR

<DefaultLibraryTemplate/>

Specifying DefaultLibraryTemplate allows you to report off all Libraries using the same query irrespective of the Library name or type. Libraries specified with ListNameFilter or ListTypeFilter will not be queried by this method.

This option can be useful if you want to query all the libraries defined in the scope when you know that they all share common columns that you can query against.

OR

<DefaultListTemplate/>

Specifying DefaultListTemplate allows you to report off all Lists using the same query irrespective of the List name or type. Lists specified with ListNameFilter or ListTypeFilter will not be queried by this method.

This option can be useful if you want to query all the lists in the scope when you know that they all share common columns that you can query against.

<ProjectFields>

Project Statement Join

The Project Fields node is for detailing the columns from the Project Statement that you would like to be able to include on the same row as items from this list in a report. Columns you add from the Project Statement will be available for selection in the web part configuration page.

<Field name=""

Specify the internal column name of a column in the Project Statement that you want to include in the query.

This name must either be included as a column in the DataTable or be mapped to a column in the DataTable using the 'columnName' attribute.

columnName=""/>

This is an optional attribute that maps the column named in <Field name=?????? to a different DataTable column name. The columnName is the title you use in the DataTable.

Please see Datatable Column Mapping Scenarios for an explanation of the scenarios where you would need to do this.

</ProjectFields>

<QueryFields>

The columns in the list that are to be included in the query.

<Field name=""

Specify the internal column name of a column you want to include in the query. You must have at least one Field node and generally you will have a number of them. All data to be returned to the report must be listed in one of these nodes.

Unless you use alternate mapping by using the columnName attribute, this is the name you must use in the DataTable.

columnName=""/>

This is an optional attribute that maps the column named in <Field name=?????? to a different DataTable column name. The columnName is the title you use in the DataTable.

Please see Datatable Column Mapping Scenarios for an explanation of the scenarios where you would need to do this.

</QueryFields>

<QueryCaml> </QueryCaml>

Please refer to the Working with Query CAML section for more information on using CAML in BrightWork Reporter.

<RowLimit>

The optional row limit feature allows you to limit the number of items returned in the report on a per list basis.

For example, <RowLimit>5</RowLimit> means only the first 5 items returned will be displayed.

Tip: use the <OrderBy> CAML node to sequence the data returned.

</RowLimit>

<QueryScope></QueryScope>

The QueryScope node specifies what will be returned:

Valid values include:

  • Default
    (Top Level Items and Folders) This means that only top level items and top level folders are returned by the report. Items in folders and subfolders are not returned by the report.
  • Files Only
    (Top Level Items Only) This means that only top level items are returned by the report. Folders and items in folders are not returned by the report.
  • Recursive
    (All Items) This is the default setting. It means that items in folders and subfolders are returned by the report but not folders.
  • Recursive All
    (All Item and Folders) This means all items and all folders are returned by the report.

For example: <QueryScope>Default</QueryScope>

</ListQueryTemplate>

</ListQueryTemplates>

Datatable Column Mapping Scenarios

columnName=""/> is an optional attribute, in the WebQueryTemplates and ListQueryTemplates nodes, that enables you to map the column named in <Field name=?????? to a different DataTable column name. Normally, the Field name is the column name you use in the DataTable; however, when you use the optional columnName attribute, this maps to the colunm name attribute in the DataTable.

The scenarios where you would need to do this include:

  • Mapping two columns with a different name to the same column
    If you had two columns that performed essentially the same function, but had different internal names, you can map them to a single column in the DataTable.
    For example, the Assigned To column is called AssignedTo in most lists; however, in the Project Deliverable Library, the Assigned to column has an internal name of AssignedToUser. The code used to remedy this is displayed below.

<DataTable>
<UserColumn name="AssignedTo" caption="Assigned To" />
???..


<ListQueryTemplate>
<ListTypeFilter listType="720" />
<QueryFields>
<Field name="AssignedToUser" columnName="AssignedTo" />

  • Mapping two columns with the same name to the different columns
    If you had two columns in two separate lists that had the same name, but actually performed different functions, you could distinguish between them by mapping one of them to a different name - otherwise they will roll up under the same column in the report. With regard to the Project Fields, the best example of this is the Title column.
  • Mapping a column with a number as a leading character to one that is acceptable to the DataTable
    DataTable column names cannot have a number as a leading character. If a column has a number as a leading character you will have to update so that the number is not at the start (e.g. from 07_Feb_Sales to Feb_Sales_07 - the code used to remedy this is displayed below).

<DataTable>
<NumberColumn name="Feb_Sales_07" caption="Feb Sales 07" numberOfDecimals="TwoDecimals" />
???..

<ListQueryTemplate>
<ListTypeFilter listType="720" />
<QueryFields>
<Field name="07_Feb_Sales" columnName=" Feb_Sales_07" />

ProjectMetrics Joins

The ProjectMetrics node is for the Project Metrics list columns that you want to join to Project Statements in reports.

<ProjectMetrics>

<Metric id=" "

This is where you specify the Metric ID.

metricValueColumn=" "

Specify the Data Table column to map the Metric Value column to.

targetValueColumn=" "

Specify the Data Table column to map the Metric Target Value column to.

indicatorColumn=" "

Specify the Data Table column to map the Metric Indicator Icon column to.

indicatorStatusColumn=" "

Specify the Data Table column to map the Metric Indicator Status column to.

formattedMetricValueColumn=" "

Specify the Data Table column that you want to map the Metric Value column to.

formattedTargetValueColumn=" "

Specify the Data Table column that you want to map the Metric Value column to.

formattedWarningValueColumn=" "

Specify the Data Table column that you want to map the Metric Value column to.

formattedDangerValueColumn=" "

Specify the Data Table column that you want to map the Metric Value column to.

/>

</ProjectMetrics>

Was this article useful?

Back to Top