Macro reference

Standard Macros

Standard macros appear on the editing toolbar and can be created using the Macro Builder. If you are are familiar with Mingle macros and MQL syntax, you can also write macros by hand by clicking the Mingle icon in the editing toolbar.

Project variables are available as values for most parameters on the standard macros. Any project variable data types which match the types of any chart parameters can be used to generate charts. For example, you can use the date project variable called (Release Start Date) in 'x-labels-start' in data series chart.
You can also use THIS CARD.property (where property is any property name) as a value for most parameters on the standard macros. Any property data types which match the types of any chart parameters can be used in THIS CARD.property to generate charts. For example, you can use THIS CARD."Start Date" as the value of the parameter 'x-labels-start' on the data series chart. This will restrict the x-axis to start on the value of the "Start Date" property on the card where it is used.
Macro markup is space sensitive and we advise you to stick to the indentation scheme specified in the examples if you write your macro by hand.

Charts

To create a chart or graph with data from a Mingle project(s), you can use a Mingle macro. You can either 1) hand-type the macro by clicking the orange Mingle icon on the editing toolbar or 2) insert a template macro using the Macro Builder.

See Mingle tips and tricks for hints on macro syntax, chart layout and chart sizing, and using project variables in charts.

Data series chart

A burnup chart showing the number of points of scope for stories in each card status over time. Trend lines have been added to project into the future.

Mingle contains two charts that can create burnup and burndown charts. This guide helps you understand the difference between them.

  data-series-chart 
    conditions: 'Release' = (Current Release) AND 'Type' = 'Story' AND 'Iteration' IS NOT NULL
    x-labels-conditions: Type = Iteration
    x-title:  Iteration
    y-title:  Total Scope
    show-start-label: true
    data-point-symbol: diamond
    data-labels: true    
    cumulative: true
    chart-height: 500
    chart-width: 800
    plot-height: 375
    plot-width: 500
    series: 
    - label: Scope
      color: black   
      data: SELECT 'Added to Scope in Iteration', SUM('Planning Estimate') 
    - label: Analysis complete
      color: orange
      data: SELECT 'Analysis Completed in Iteration', SUM('Planning Estimate') WHERE 'Analysis Completed in Iteration' IS NOT NULL
      trend: true
    - label: Development complete
      color: blue
      data: SELECT 'Development Completed in Iteration', SUM('Planning Estimate') WHERE 'Development Completed in Iteration' IS NOT NULL
      trend: true
    - label: Accepted
      color: green
      data: SELECT 'Accepted in Iteration', SUM('Planning Estimate') WHERE  'Accepted in Iteration' IS NOT NULL 
      trend: true

Preview

When applying trend lines to burn up charts beware of the trend-scope and trend-ignore options as these are used to determine how many data points are used to plot the trend line. In particular:

a trend line that only has a single data point will be drawn vertically
to create a trend based on completed work only use the trend-ignore: zeroes-at-end-and-last-value option which will not include any zero values or the last none zero value

Parameters
Chart-level options
Name	Meaning	Required	Default value
three-d	One of [true/false] indicating whether to plot in a 3-d style	No
x-title	Specify the title for the x-axis. Defaults to name of property that is driving the labels.	No
y-title	Specify the title for the y-axis. Defaults to the aggregation of the first data series.	No
chart-height	Specify the height of the entire chart (plot area plus legend) in pixels.	No	300
chart-width	Specify the width of the entire chart (plot area plus legend) in pixels.	No	400
plot-height	Specify the height of the plot area in pixels.	No	220
plot-width	Specify the width of the plot area in pixels.	No	230
plot-x-offset	Specify the length of the offset of the plot area from the right of the chart area in pixels. Increasing the offset will move the plot closer to the centre of the chart area.	No	50
plot-y-offset	Specify the length of the offset of the plot area from the top of the chart area in pixels. Increasing the offset will move the plot closer to the centre of the chart area.	No	10
label-font-angle	Angle of the x-axis labels.	No	45
legend-top-offset	Specify the offset of the legend from the top of the chart area in pixels. Increasing the offset will move the legend lower in the chart area.	No	5
legend-offset	Specify the offset of the legend from the right side of the plot area in pixels. A negative offset will move the legend inside the plot area.	No	20
legend-max-width	Specify the maximum width of the legend in pixels. Legend labels will wrap to fit the maximum width.	No	120
cumulative	One of [true/false] indicating whether the data of each series accumulates or is stand-alone. Defaults to false.	No
series	A list of the actual data series to be plotted. At least one series is required. Markup format is same basic format as stack-bar-chart.	Yes
conditions	MQL condition narrowing the the set of cards available to each series.	No
x-labels-property	Allow user to specify a property for label values. Defaults to the property definition specified by the first data series. In either case, all values will be used as labels.	No
x-labels-start	Allow user to specify the start value for labels on the x axis. Must be a valid, existing value for the x labels property. Defaults to first value for the x labels property. When x labels property is a date property, the value can be earlier than any existing value. Note that when plotting a cumulative chart, this parameter does not impact the scope of included cards in any data accumulation. I.e, this parameter only impacts the scope of what is drawn. Use the conditions parameter to restrict the cards to be accumulated.	No
x-labels-end	Allow user to specify the end value for labels on the x axis. Must be a valid, existing value for the x labels property. Defaults to last value for the x labels property. When x labels property is a date property, the value can be later than any existing value. Note that when plotting a cumulative chart, this parameter does not impact the scope of included cards in any data accumulation. I.e, this parameter only impacts the scope of what is drawn. Use the conditions parameter to restrict the cards to be accumulated.	No
x-labels-step	Allow user to specify that only every N labels should be displayed on the x-axis. This is useful when plotting against a property with many values, such as date properties. Default is 1, except in the case of date properties with more than 14 values, in which case the default is 7.	No
x-labels-conditions	When charting against a card property, allow the user to specify conditions to narrow the set of cards to be used as x labels. Does not work when charting against text, numeric, or user properties. Use x-labels-start and x-labels-end to restrict the set of labels for those property types.	No
x-labels-tree	When charting against a card property, this parameter allows the user to specify a tree from which to define the x-labels values. Using this parameter will mean x-labels are displayed as hierarchical names and card numbers will not be used. In practice this is likely only to be needed in the situation where charts are used to visualize data from multiple projects and where the cards that represent the data in these projects (e.g. "Release 1" or "Iteration 1") are not the same card numbers.	No	If not specified card numbers will be used to as x-labels values.
show-start-label	One of [true/false] specifying whether to add a data point at the start of your series to show an implied starting point. This is especially useful when wanting to show a down-from line starting from the down-from value, or when wanting to show a line starting from 0. The default value is false unless any series specifies a 'down-from' parameter, in which case the default is true. The label can be set with the 'start-label' parameter.	No
start-label	Any text to be used as the label when using the 'show-start-label' parameter.	No
Chart-level options that can be overridden by any individual series
Name	Meaning	Required	Default value
chart-type	One of [line/area/bar] specifying how to draw each series. Default is line. Can be overridden by an individual series type.	No	line
line-width	Line width for any series of type line. Default is 3.	No
line-style	One of [solid/dash] specifying line style for any series of type line. Default is solid.	No
trend	One of [true/false] specifying whether to plot each series' data beyond the point at which the series contains no new data. Defaults to false. Can be overridden by an individual series.	No
trend-scope	Can be 'all' or an integer number. Specify the number of 'recent' data points (from the set of relevant data points-see trend-ignore) to be used in plotting the trend. Defaults to 'all.' Can be overridden by an individual series.	No
trend-ignore	One of [none/zeroes-at-end/zeroes-at-end-and-last-value] specifying which data points at the end of the series to ignore when plotting the trend. The 'zeroes-at-end' option ignore all zeroes in the series beyond the last non-zero value. The 'zeroes-at-end-and-last-value' option ignores all zeroes in the series beyond the last non-zero value as well as that non-zero value, assuming that it's an 'in-progress' item. The 'none' option considers all data points in the series. The default is 'zeroes-at-end-and-last-value.' Can be overridden by an individual series.	No
trend-line-color	Specifies the color of the trend line. Defaults to same color as actual data line. Can be overridden by an individual series.	No
trend-line-style	One of [dash/solid] specifying the line's style. The default is dash. Can be overridden by an individual series.	No
trend-line-width	Any integer number greater than 0 specifying the line's width. Can be overridden by an individual series.	No
data-point-symbol	One of [none/square/diamond] specifying whether to plot the data points. Default value is 'none.' Can be overridden by a series. Only applicable to chart-type of 'line'	No
data-labels	One of [true/false] specifying whether to show the value of each data point. Default value is 'false.' Can be overridden by a series.	No
project	Any valid project identifier, specifying which project’s cards will be plotted by this chart. Authorization will be enforced upon view. That is, if a user does not have access to a project, the card or wiki page will not be available for that user.	No	Default is the project to which the page or card containing the macro belongs to.
Series-level options
Name	Meaning	Required	Default value
line-width	Overrides chart-level setting. See chart-level description.	No
line-style	Overrides chart-level setting. See chart-level description.	No
label	Any text specifying name of series to be displayed in the legend.	No
color	And text specifying a standard web color indicating the color to be used when plotting the series.	No
data	MQL query specifying the property and aggregation (and optional WHERE clause) for this series.	Yes
type	Overrides chart-level 'chart-type' setting. See chart-level description.	No
data-point-symbol	Overrides chart-level setting. See chart-level description. Only applicable to type of 'line.'	No
data-labels	Overrides chart-level setting. See chart-level description.	No
down-from	MQL query specifying a value from which this series will be plotted down from. This is how Mingle supports burn downs. E.g. SELECT SUM(Estimate) WHERE 'Entered Scope Iteration' IS NOT NULL	No
trend	Overrides chart-level setting. See chart-level description.	No
trend-scope	Overrides chart-level setting. See chart-level description.	No
trend-ignore	Overrides chart-level setting. See chart-level description.	No
trend-line-color	Overrides chart-level setting. See chart-level description.	No
trend-line-style	Overrides chart-level setting. See chart-level description.	No
trend-line-width	Overrides chart-level setting. See chart-level description.	No
project	Any valid project identifier, specifying which project’s cards will be plotted by this series. Authorization will be enforced upon view. That is, if a user does not have access to a project, the card or wiki page will not be available for that user.	No	Defaults to what is defined at the chart level.

Daily history chart

A chart showing the number of points of scope for stories in each card status over time.

Mingle contains two charts that can create burnup and burndown charts. This guide helps you understand the difference between them.

    daily-history-chart
      aggregate: SUM('Pre-Release Estimate')
      chart-conditions: release = 'Release 3' AND Type = Story
      start-date: 07 Jun 2010
      end-date: 18 Jun 2010
      chart-height: 350
      chart-width: 500
      y-title: Total Scope
      series:
      - label: all
        color: gray
        line-width: 1
      - label: must
        color: black
        conditions: 'Release Priority' = must
      - label: analysis complete
        color: green
        line-width: 2
        conditions: 'story status' > 'analysis in progress'
      - label: dev complete
        color: orange
        line-width: 2
        conditions: 'story status' > 'development in progress'
      - label: signed off
        color: purple
        line-width: 2
        conditions: 'story status' > 'signoff in progress'
      - label: Closed
        color: blue
        line-width: 2
        conditions: 'story status' = 'closed'

Preview

Because the daily history chart works with historical data, there are several restrictions for this chart. Although the chart-conditions and series conditions accept most MQL conditions, due to the nature of the daily history chart there are some restrictions to the MQL which can be used with these parameters. In particular, today, current user and THIS CARD.property cannot be used in the MQL for the chart-conditions and series conditions parameters. Project variables and THIS CARD are allowed with these parameters. Although THIS CARD.property cannot be used in chart-conditions and series conditions parameters, it can be used with other parameters. E.g., you could set the start-date parameter to THIS CARD."Start date". Also, because aggregate property values are not versioned like other properties, they should not be used in this chart, either in any MQL or parameters.

Parameters
Chart-level options
Name	Meaning	Required	Default value
aggregate	The aggregate that is applied to every series.	Yes
chart-conditions	MQL condition narrowing the the set of cards available to each series.	No
start-date	Specify the start date for the chart. This is displayed on the x-axis, and must be a valid date.	Yes
end-date	Specify the end date for the chart. This is displayed on the x-axis, and must be a valid date.	Yes
x-labels-step	Allow user to specify that only every N labels should be displayed on the x-axis.	No	1
x-title	Specify the title for the x-axis. Defaults to name of property that is driving the labels.	No
y-title	Specify the title for the y-axis. Defaults to the aggregation of the first data series.	No
chart-height	Specify the height of the entire chart (plot area plus legend) in pixels.	No	300
chart-width	Specify the width of the entire chart (plot area plus legend) in pixels.	No	400
plot-height	Specify the height of the plot area in pixels.	No	220
plot-width	Specify the width of the plot area in pixels.	No	230
plot-x-offset	Specify the length of the offset of the plot area from the right of the chart area in pixels. Increasing the offset will move the plot closer to the centre of the chart area.	No	50
plot-y-offset	Specify the length of the offset of the plot area from the top of the chart area in pixels. Increasing the offset will move the plot closer to the centre of the chart area.	No	10
label-font-angle	Angle of the x-axis labels.	No	45
legend-top-offset	Specify the offset of the legend from the top of the chart area in pixels. Increasing the offset will move the legend lower in the chart area.	No	5
legend-offset	Specify the offset of the legend from the right side of the plot area in pixels. A negative offset will move the legend inside the plot area.	No	20
legend-max-width	Specify the maximum width of the legend in pixels. Legend labels will wrap to fit the maximum width.	No	120
scope-series	Specify the scope series for forecasting charts and fixed-date charts. Valid values are labels used in series. Used together with completion-series.	No
completion-series	Specify the completion series for forecasting charts and fixed-date charts. Valid values are labels used in series. Used together with scope-series.	No
series	A list of the actual data series to be plotted. At least one series is required. Markup format is same basic format as stack-bar-chart.	Yes
target-release-date	Specify the target release date for fixed-date charts. Used together with scope-series and completion-series.	No
Chart-level options that can be overridden by any individual series
Name	Meaning	Required	Default value
line-width	Line width for any series of type line.	No	1
Series-level options
Name	Meaning	Required	Default value
line-width	Overrides chart-level setting. See chart-level description.	No
label	Any text specifying name of series to be displayed in the legend.	No
color	And text specifying a standard web color indicating the color to be used when plotting the series.	No
conditions	MQL condition narrowing the cards shown in each series. This is combined with the chart-conditions parameter.	Yes

Forecasting chart

The forecasting chart is an extension of the daily history chart and shows when your team may deliver -- based on your definition of “done” -- in relation to changes (0%, 50% or 150%) in remaining scope.

You can use the forecasting chart to help answer the question: "When will we be done?" Because the forecasting is based on the average actual velocity to date, you might not see the forecasting dates at the very beginning of your release/iteration. However, as your team progresses, the historical information will be captured, which will allow Mingle to calculate and present the forecasting information for you.

  daily-history-chart
    aggregate: count(*)
    chart-conditions: type = story  AND status > new AND release = (current release)
    start-date: 16-january-2012
    end-date: 14-may-2012
    x-labels-step: 28
    chart-height: 310
    chart-width: 800
    plot-width: 610
    y-title: Estimate
    scope-series: All Stories
    completion-series: Completed Stories
    series:
    - label: All Stories
      color: #808080
      line-width: 2
    - label: Completed Stories
      color: red
      conditions: 'status' = 'closed'
      line-width: 2

Preview

Forecasting chart is one of the two variations on the daily history chart, the other one is fixed-date chart . The special parameters used for forecasting charts are as below. For a complete list of supported parameters, please refer to the parameter table of daily history chart .

Parameters
Name	Meaning	Required	Default value
scope-series	Specify the scope series for forecasting charts and fixed-date charts. Valid values are labels used in series. Used together with completion-series.	Required for forecasting chart and fixed-date chart
completion-series	Specify the completion series for forecasting charts and fixed-date charts. Valid values are labels used in series. Used together with scope-series.	Required for forecasting chart and fixed-date chart

Fixed date chart

The fixed-date chart is an extension of the daily history chart and shows how much work may be incomplete by a given date.

You can use the fixed-date chart to help answer the question: "What can we get done by date x?". It is intended to signal when you may not deliver everything you planned by a given date. When the actual velocity (average velocity to date) is estimated to create a burn-up that falls short of total scope, team members can have a conversation about which features are ready to be delivered and which may have to be left undelivered.

  daily-history-chart
    aggregate: count(*)
    chart-conditions: type = story  AND status > new AND release = (current release)
    start-date: 16-january-2012
    end-date: 14-may-2012
    x-labels-step: 28
    chart-height: 310
    chart-width: 800
    plot-width: 610
    y-title: Estimate
    scope-series: All Stories
    completion-series: Completed Stories
    target-release-date: 24-April-2012
    series:
    - label: All Stories
      color: #808080
      line-width: 2
    - label: Completed Stories
      color: red
      conditions: 'status' = 'closed'
      line-width: 2

Preview

Fixed-date chart is one of the two variations on the daily history chart, the other one is forecasting chart . The special parameters used for fixed-date charts are as below. For a complete list of supported parameters, please refer to the parameter table of daily history chart .

Parameters
Name	Meaning	Required
scope-series	Specify the scope series for forecasting charts and fixed-date charts. Valid values are labels used in series. Used together with completion-series.	Required for forecasting chart and fixed-date chart
completion-series	Specify the completion series for forecasting charts and fixed-date charts. Valid values are labels used in series. Used together with scope-series.	Required for forecasting chart and fixed-date chart
target-release-date	Specify the target release date for fixed-date charts. Used together with scope-series and completion-series.	Required for fixed-date chart

Stacked bar chart

Suppose you are tracking when cards enter scope, have been fully prepared for development, and are completed. You would like a chart that can display a running total of cards in each of those three states at the end of each iteration. To most effectively use the stack-bar-chart to display this sort of chart you will need to track three separate 'iteration' properties, each specifying when the card entered a particular state.

Macro markup is space sensitive and we advise you to stick to the indentation scheme specified in the example. If you add project as a parameter this needs to be added to a new line as shown in the markup below.

  stack-bar-chart
    conditions: 'Release' = '2.3' AND 'Type' = 'Story' AND NOT 'Iteration' = NULL
    labels: SELECT DISTINCT 'Iteration'
    cumulative: true
    project: agile
    series:
    - label: Closed
      color: green
      type: bar
      data: SELECT 'Closed Iteration', COUNT(*) WHERE NOT 'Closed Iteration' = NULL
      combine: overlay-bottom
    - label: Analysis Complete
      color: yellow
      type: bar
      data: SELECT 'Analysis Complete Iteration', COUNT(*) WHERE NOT 'Analysis Complete Iteration' = NULL
      combine: overlay-bottom
    - label: Entire Scope
      color: blue
      type: bar
      data: SELECT 'Entered Scope Iteration', COUNT(*) WHERE NOT 'Entered Scope Iteration' = NULL
      combine: total

Preview

Parameters
Chart-level options
Name	Meaning	Required	Default value
conditions	MQL condition that restricts the cards which will be included in all of the data series	No	If not specified, all cards will be considered for each series.
labels	MQL query that returns a list of values to be used as labels across the x-axis. Using the example above, all values for a card type 'Iteration' are returned and used as labels for the x-axis in the stack bar chart. You must use 'SELECT' statement. This works similarly as x-labels-conditions or x-labels-property on data series chart.	No	If not specified, the values of the first property specified on the 'data' parameter on 'series level' will be used as the x-axis labels.
cumulative	Whether each data series includes all previous series. I.e., if a bar shows only data for that x-axis label, or a running total, including its own data and all previous bars.	No	TRUE
x-label-start	Allow user to specify the start value for labels on the x axis. Must be a valid, existing value for the x labels property. Defaults to first value for the x labels property. When x labels property is a date property, the value can be earlier than any existing value. Note that when plotting a cumulative chart, this parameter does not impact the scope of included cards in any data accumulation. I.e, this parameter only impacts the scope of what is drawn. Use the conditions parameter to restrict the cards to be accumulated.	No	If not specified, the first label value returned by the label query will be used.
x-label-end	Allow user to specify the end value for labels on the x axis. Must be a valid, existing value for the x labels property. Defaults to last value for the x labels property. When x labels property is a date property, the value can be later than any existing value. Note that when plotting a cumulative chart, this parameter does not impact the scope of included cards in any data accumulation. I.e, this parameter only impacts the scope of what is drawn. Use the conditions parameter to restrict the cards to be accumulated.	No	If not specified, the last label value returned by the label query will be used.
x-label-step	Allow user to specify that only every N labels should be displayed on the x-axis. This is useful when plotting against a property with many values, such as date properties. Default is 1, except in the case of date properties with more than 14 values, in which case the default is 7.	No	If not specified, the following defaults will be used depending on what kind of property is used on the x-axis. 5 days at a time for Date Properties. Every label value for others.
x-labels-tree	When charting against a card property, this parameter allows the user to specify a tree from which to define the x-labels values. Using this parameter will mean x-labels are displayed as hierarchical names and card numbers will not be used. In practice this is likely only to be needed in the situation where charts are used to visualize data from multiple projects and where the cards that represent the data in these projects (e.g. "Release 1" or "Iteration 1") are not the same card numbers.	No	If not specified card numbers will be used to as x-labels values.
x-title	The title for the x-axis. Use this to override the default if there is a better name to explain what the labels represent.	No	If not specified, the property name of the series with a combine of 'total' series will be used. If no series is specified with a of 'total', the property of the very first series will be used.
y-title	The title for the y-axis.	No	If not specified, this will default to the property name of the first series.
three-d	If set to true, 3-d effects will be turned on. Data series of type bar will be shown as rectangular columns. Data series of type area will be shown in different layers, stacked one behind the other. Line graphs do not benefit much from 3-d effects.	No	false
chart-height	Specify the height of the entire chart (plot area plus legend) in pixels.	No	300
chart-width	Specify the width of the entire chart (plot area plus legend) in pixels.	No	400
plot-height	Specify the height of the plot area in pixels.	No	220
plot-width	Specify the width of the plot area in pixels.	No	230
plot-x-offset	Specify the length of the offset of the plot area from the right of the chart area in pixels. Increasing the offset will move the plot closer to the centre of the chart area.	No	50
plot-y-offset	Specify the length of the offset of the plot area from the top of the chart area in pixels. Increasing the offset will move the plot closer to the centre of the chart area.	No	10
label-font-angle	Angle of the x-axis labels.	No	45
legend-top-offset	Specify the offset of the legend from the top of the chart area in pixels. Increasing the offset will move the legend lower in the chart area.	No	5
legend-offset	Specify the offset of the legend from the right side of the plot area in pixels. A negative offset will move the legend inside the plot area.	No	20
legend-max-width	Specify the maximum width of the legend in pixels. Legend labels will wrap to fit the maximum width.	No	120
series	A list of data series. Each series represents a portion of each bar on the bar chart. When type is set to area or line, each series represents a different chart line. (Note that each series need not select the same property for this chart to be meaningful. Each series must select data that is of the same type and same scale, but not the exact same property.)	Yes. At least one series must be specified.
Chart-level options that can be overridden by any individual series
Name	Meaning	Required	Default value
project	Any valid project identifier, specifying which project’s cards will be plotted by this chart. Authorization will be enforced upon view. That is, if a user does not have access to a project, the card or wiki page will not be available for that user.	No	Default is the project to which the page or card containing the macro belongs to.
Series-level options
Name	Meaning	Required	Default value
label	The name of this series to appear in the chart's legend	No
color	A hex string or standard web color to be used when rendering a series	No
data	A MQL query that selects property values and an aggregation of those values. The property values will be used to group the aggregation. The aggregation represents how much of the bar will be represented by this series.	Yes
combine	How to combine the value of this series with the values of other series in a given bar. Valid values are total, overlay-top, and overlay-bottom. Use total to specify that a series represents the full height of the bar. Use overlay-bottom to have this series render in a stack, starting at the bottom of the bar. Use overlay-top to have this series render in a stack, starting at the top of the bar.	Yes
type	How to draw a series. Valid values are area, line, and bar.	No	bar
hidden	Will the graph for this data series show up in the final graph? Use this to not show data series that are only used for calculation. This is similar to setting the series color to transparent.	No	false
project	Any valid project identifier, specifying which project’s cards will be plotted by this series. Authorization will be enforced upon view. That is, if a user does not have access to a project, the card or wiki page will not be available for that user.	No	Defaults to what is defined at the chart level.

Ratio bar chart

Display a bar chart with each bar showing the percentage of closed stories in a particular feature. In terms of card properties, what we want to show is this: for all cards with property 'Type' equal to 'Story,' calculate the percentage (based upon the SUM of the 'Size' property) of cards with property 'Status' equal to 'Closed.'

    ratio-bar-chart
      totals: SELECT Feature, SUM(Size) WHERE Type = Story
      restrict-ratio-with: Status = Closed
      project: agile

Preview

Parameters
Name	Meaning	Required	Default value
totals	A MQL query returning the full scope of the chart. The MQL query must return a two column results set. The values in the first column will be the labels for the result set. The values in the second column represent the full height of the bars (the y-axis).	Yes
restrict-ratio-with	A MQL condition that represents the portion of each bar to be filled in with color. The results of the totals parameter represent 100% of the height.	Yes
color	A hex string representing the color of the bars. Can optionally be any standard web color name.	No	LightBlue
x-title	The title for the x-axis. Use this to override the default if there is a better name to explain what the labels represent.	No	If not specified, the name of the first property in the totals query will be used.
y-title	The title for the y-axis.	No	If not specified, this will default to the property name of the property being plotted in the totals query.
three-d	If set to true, 3-d effects will be turned on. The data will be shown as rectangular columns.	No	false
chart-height	Specify the height of the entire chart (plot area plus legend) in pixels.	No	300
chart-width	Specify the width of the entire chart (plot area plus legend) in pixels.	No	400
plot-height	Specify the height of the plot area in pixels.	No	220
plot-width	Specify the width of the plot area in pixels.	No	230
plot-x-offset	Specify the length of the offset of the plot area from the right of the chart area in pixels. Increasing the offset will move the plot closer to the centre of the chart area.	No	50
plot-y-offset	Specify the length of the offset of the plot area from the top of the chart area in pixels. Increasing the offset will move the plot closer to the centre of the chart area.	No	10
label-font-angle	Angle of the x-axis labels.	No	45
project	Any valid project identifier, specifying which project’s cards will be plotted by this chart. Authorization will be enforced upon view. That is, if a user does not have access to a project, the card or wiki page will not be available for that user.	No	Default is the project to which the page or card containing the macro belongs to.

Pie chart

Display a pie chart showing a percentage breakdown of all bugs (cards with a property 'Type' set to 'Bug') by status

Macro markup is space sensitive and we advise you to stick to the indentation scheme specified in the example.

  pie-chart
    data: SELECT Feature, COUNT(*) WHERE Type = Story

Preview

Parameters
Name	Meaning	Required	Default value
data	MQL query returning the data to be represented by the pie chart. The query must return a two-column result set. The values in the first column represent the chart labels. The values in the second column represent the portion of the pie for that row. Aggregation is supported.	Yes
project	Any valid project identifier, specifying which project’s cards will be plotted by this chart. Authorization will be enforced upon view. That is, if a user does not have access to a project, the card or wiki page will not be available for that user.	No	Default is the project to which the page or card containing the macro belongs to.
chart-width	Specify the width of the entire chart (plot area plus labels) in pixels.	No	440
chart-height	Specify the height of the entire chart (plot area plus labels) in pixels.	No	300
radius	Specify the length of the pie radius in pixels.	No	100

Table Macros

Table - based on a query

Display a table with two columns, name and number - one row for each card that has a property 'Priority' set to 'Critical' and a property 'Release' set to 'Release One.' As usual, quotes are used only when grouping words with spaces in them.

    table 
      query: SELECT number, name WHERE Priority = Critical AND Release = 'Release One'
      project: project_one

This is how your macro will appear when you insert it into your card:

This table contains links to the cards. If you would like links to cards in your table, include number as one of the properties in the query.
Macro markup is space sensitive and we advise you to stick to the indentation scheme specified in the example. If you add project as a parameter this needs to be added to a new line as shown in the markup below.

Parameters
Name	Meaning	Required	Default value
query	A custom MQL query, the results of executing this query will be shown in the table.	One, and only one, of query or view is required.
project	Any valid project identifier, specifying which project’s cards will be displayed. Authorization will be enforced upon view. That is, if a user does not have access to a project, that data series will not be included in the chart for that user. Default is the project to which the page or card containing the macro belongs.	No	Default is the project to which the page or card containing the macro belongs to.

Table - based on a favorite

Render a table containing all cards that are a part of the favorite named 'Release One'. Quotes may be omitted if the favorite name does not contain any spaces.

  table view: 'Release One'
  project: project_one

Preview

Parameters
Name	Meaning	Required	Default value
view	A previously saved favorite, the contents of which will be shown in the table.	One, and only one of query or view is required.
project	Any valid project identifier, specifying which project’s view will be displayed. Authorization will be enforced upon view. That is, if a user does not have access to a project, that data series will not be included in the chart for that user. Default is the project to which the page or card containing the macro belongs.	No	Default is the project to which the page or card containing the macro belongs to.

Pivot table

Display a pivot table summing the estimates for in-scope stories by priority (cards of type 'Story' and property 'Story Status' is not set to 'Out of Scope') for each status. The table will not display any empty rows or columns, but will display a total for each status in the bottom row.

{{
  pivot-table
    conditions: Type = Story AND 'Story Status' != 'Out of Scope'
    aggregation: SUM('Story Estimate - Original')
    rows: Priority
    columns: 'Story Status'
    empty-rows: true
    empty-columns: true
    totals: true
    project: agile
}}

Preview

Chart level options
Name	Meaning	Required	Default value
aggregation	The database function to perform across all cards having the row and column values for a particular cell. The result of this function will display in the cell	No	COUNT(*)
columns	The card property whose values make up the columns of the table	Yes
conditions	A custom MQL condition clause that restricts the cards which are to be aggregated	No	If not specified, all cards are aggregated.
empty-columns	Should the table contain empty columns	No	TRUE
empty-rows	Should the table contain empty rows	No	TRUE
links	Should the cell contain a link to a card list containing the cards specified by the cell's row and column values	No	TRUE
project	Any valid project identifier, specifying which project’s cards will be plotted by this chart. Authorization will be enforced upon view. That is, if a user does not have access to a project, that data series will not be included in the chart for that user. Default is the project to which the page or card containing the macro belongs.	no
rows	The card property whose values make up the rows of the table	Yes
totals	Should column totals display	No	FALSE

Query macros

Average query

Calculate average story size

{{
  average query: SELECT size WHERE type = story
  project: project_one
}}

Preview

Parameters
Name	Meaning	Required	Default value
query	A custom MQL query, the results of executing this query will be shown as an average value.	Yes
project	Any valid project identifier, specifying which project’s cards will be used to calculate the average query. Authorization will be enforced upon view. That is, if a user does not have access to a project, that data series will not be included in the chart for that user. Default is the project to which the page or card containing the macro belongs.	No	Default is the project to which the page or card containing the macro belongs to.

Value query

Calculate the total size of all stories

{{
  value query: SELECT SUM('size') WHERE Type = Story
  project: project_one
}}

Preview

Parameters
Name	Meaning	Required	Default value
query	A custom MQL query, the results of executing this query will be shown as an value.	Yes
project	Any valid project identifier, specifying which project’s cards will be used to calculate the value query. Authorization will be enforced upon view. That is, if a user does not have access to a project, that data series will not be included in the chart for that user. Default is the project to which the page or card containing the macro belongs.	No	Default is the project to which the page or card containing the macro belongs to.

Other macros

Project macro and Project as a chart option level

Use Project macro to get project identifier

The user can display the identifier of the current project with the following markup:

{{ project }}

Use Project as a chart level option to create charts using another project's data

The markup below shows how to create a pie chart using data from another project by using the project identifier, for example great_bank, as the value for project chart level option. This will allow users to access another project's data when creating charts on the current project.

See cross project reporting for more information on using another project's data when creating charts on the current project.

{{
  pie-chart
    data: SELECT 'Feature', Count(*) WHERE Type = Story and 'Story Status' = Accepted
    project: great_bank
}}

Preview

Project variable value macro

Displays the current value of the specified project variable

{{project-variable name: (current release)}}

where 'current release' is the name of a project variable in the project.

This project-variable macro cannot be used as a value of other macro parameters. For example, although you may expect to use this macro to specify x-label-start on a data-series-chart this functionality is not supported.

Parameters
Name	Meaning	Required	Default value
name	Name of a project variable.	Yes
project	Any valid project identifier, specifying which project’s project variable is being referred to.	No	Default is the project to which the page or card containing the macro belongs to.

Go pipeline status macro

This macro allows the display of the current status of a Go pipeline in a Mingle wiki page or card. This allows users to view current project status across the two products in a single view.

For this macro to work, the Mingle and Go administrators must first configure the display of Go gadgets in Mingle.

      {{
        pipeline-status-gadget
          go-url: https://go.example.com
          pipeline-name: CompileAndTest
      }}

Parameters
Name	Meaning	Required	Default value
go-url	The base URL for your Go instance, with or without trailing slash. If you run go with an app context, be sure to include that in the value, e.g, if you're Go URLs look like https://example.com/dev/go/pipelines/... this value would be https://example.com/dev	Yes	N/A
pipeline-name	The name of the Go pipeline. The case must match the case specified in the Go configuration.	Yes	N/A

Preview

Go pipeline status on Mingle Overview page.

When you first attempt to view this macro, you will see a message indicating that you need to authorize Mingle to access data from Go on your behalf, similar to below.

Allow Mingle to access Go data on your behalf.

Clicking the authorize link will open a popup displaying a Go page asking you whether you wish to allow Go to provide your data to Mingle such as below. If you do not currently have a current Go session you will first be asked to login to Go.

Go asks you to allow it to provide data to Mingle.

Once the user clicks the Yes button the popup will close and the pipeline status gadget will appear.

If a user authorizes on a page containing markup for multiple pipeline status gadgets only the gadget from which authorization was initiated will refresh with the gadget content. To show gadget content across the entire page, the page must be refresh in the browser.

OpenSocial gadget macro

This macro allows the display of an OpenSocial gadget within a Mingle card or page. This macro can also be useful when troubleshooting the display of Go content in Mingle.

      {{
      gadget
        url: http://hosting.gmodules.com/ig/gadgets/file/112581010116074801021/hamster.xml
        view: home
        _noCache: 1
        _debug: 1
        preferences:
          bgColor: orange
      }}

If the provider of the gadget content is using OAuth 2.0 to protect that content, your Mingle administrator can configure Mingle to act as an OAuth 2.0 capable rendering server in order to allow your Mingle users to access the protected gadget content.

At this point in time, Mingle does not support the rendering of gadgets protected by version 1.0a of OAuth.

What is OpenSocial?

Parameters
Name	Meaning	Required	Default value
url	The URL for the gadget specification XML	Yes	N/A
view	The specified view for the gadget.	It depends. Only some gadgets make use of this parameter.	N/A
_noCache	Whether to use the gadget rendering server's cache of static content, including the gadget spec XML. It is highly recommended to only use this when troubleshooting. Setting this to 1 will severely degrade Gadget and overall Mingle performance. Valid values are 0 and 1.	No	0
_debug	Whether to show detailed error messages. It is highly recommended to only use this when troubleshooting. Valid values are 0 and 1.	No	0
preferences	Any additional gadget settings, known as user preferences. Note that the preferences must be indented by 2 spaces as is common with Mingle macro markup.	Depends upon the individual gadget's requirements.	N/A

Google calendar macro

Mingle 3.2 introduced the macro to create a google calendar.

The markup below will display the public Google calendar for US holidays.

  google-calendar
    src: "http://www.google.com/calendar/embed?src=en.usa%23holiday%40group.v.calendar.google.com&ctz=America/Los_Angeles"
    width: 900
    height: 700

This macro is not available in the wiki toolbar on any cards or wiki pages. Therefore you should manually enter the markup as stated above (or copy and paste) and replace the location of your google calendar as a value of the src parameter.

Google map macro

Mingle 3.2 introduced the macro to create a google map.

The markup below will display a Google map for San Francisco.

  google-maps
    src: "http://maps.google.com/maps?ie=UTF8&hq=&hnear=San+Francisco,+California&ll=37.782655,-122.419281&spn=0.329408,0.711365&z=11"
    width: 900
    height: 750

Custom macros

Cross project macros

Mingle 3.0 includes updates to the Macro Development Toolkit to facilitate cross project reporting for program management. As an example of the cross project macro functionality available via the Macro Development Toolkit, Mingle 3.0 ships with a new macro called cross-project-rollup.

Cross project rollup

This macro does not appear in the Macro Editor. To use this macro, use the markup example below as a template for your own cross project reports.

A macro that aggregates property values across multiple projects. This macro only works with Mingle 3.0. The cross-project-rollup macro will work using the following markup:

{{
   cross-project-rollup
   project-group:  project_3_0_features_showcase, another_project_in_my_program
   rows: Feature
   rows-conditions: Feature != NULL
   columns:
   -     label: Number of stories
         aggregate: count(*)
         conditions: type = story
   -     label: Number of Must stories
         aggregate: count(*)
         conditions: priority = must and type = story
   -     label: Estimate of Must stories
         aggregate: sum(estimate)
         conditions:  priority = must and type = story
   total: true
}}

Preview

The following is a list of parameters and how they should be used with this macro:

Parameters
Chart-level options
Name	Meaning	Required	Default value
project-group	List of project identifiers	No	Current project
rows	A property. Each row is a property value. The order of the rows' property values is alphabetical by card name if a card or tree relationship property, by number if they are numeric properties, by display name and login if they are team properties, by date if they are date properties, by the bespoke order of the first project if they are text properties.	Yes
rows-conditions	MQL condition to restrict the rows shown in the table.	No
zero-value-rows	True or false. Determines whether rows with no value will be shown or not.	No	True
columns	Can have many columns. Shown in the order given in the macro markup.	Yes
Column-level options
Name	Meaning	Required	Default value
label	Label for the column. Label will default to the column aggregate if not specified.	No	Column aggregate
aggregate	Can be Count, Sum(property), Min, Max. Cannot be average. Date properties cannot be aggregated.	Yes
conditions	MQL condition to restrict the column aggregation.	No
Other options
Name	Meaning	Required	Default value
total	True or false. Sums the column and shown as row if true. Always shown as the bottom row.	No	True
sub-totals	Only applicable when the column aggregation is count or sum. Calculates a sum of the rows in the column restricted by the subtotal condition. Can have many subtotals. Shown in order given in macro markup.	No
Sub-total options
Name	Meaning	Required	Default value
conditions	MQL condition.	No	Sum total of the column
label	Label for the sub-totals. Label will default to the condition of the subtotal if not specified.	No	Conditions or, if no conditions, empty

Help documentation

Macro reference

Standard Macros

Charts

Data series chart

Preview

Daily history chart

Preview

Forecasting chart

Preview

Fixed date chart

Preview

Stacked bar chart

Preview

Ratio bar chart

Preview

Pie chart

Preview

Table Macros

Table - based on a query

Table - based on a favorite

Preview

Pivot table

Preview

Query macros

Average query

Preview

Value query

Preview

Other macros

Project macro and Project as a chart option level

Use Project macro to get project identifier

Use Project as a chart level option to create charts using another project's data

Preview

Project variable value macro

Go pipeline status macro

Preview

OpenSocial gadget macro

Google calendar macro

Google map macro

Custom macros

Cross project macros

Cross project rollup

Preview

Also see...