Table of Contents
Training Videos for Web Report Designer
🧠 These videos cover the information shown within the rest of the article. You can either read the article or watch the below videos!
Report Band Classes Video
Sections
00:33 What is the Secret to Report Designing?
01:37 What is a Report Band?
02:40 The Report Band Classes
03:21 The Report Explorer
05:08 Report Band Selection
06:11 Report Band Tasks
09:36 Top Margin Band
11:16 Report Band Visibility and Size
12:28 Report Header Band
18:45 Page Header Band
29:17 Detail Report Band
36:12 Group Header Band
51:11 Detail Band
52:49 Group Footer Band
58:21 Report Footer Band
59:24 Page Footer Band
01:01:21 Bottom Margin Band
01:03:00 Sub-Band
Web Report Designer: Training Guide Video
Sections
Below are step by step instructions that cover what is in the above video!
Roles and Permission for Web Report Designer
To add the Report Designer permission to a user role:
Go to Administration by clicking on your Profile Icon in the lower left corner.)
Select the User Management tab at the top, then click the User Roles subsection.
Select the user role from the drop down.
In the Admin grouping, check the box that says Report Designer Access
Then, click Save in the upper right.
Navigation
Once the permission for the user role has been checked, and you are assigned that role, you can now access the Web Report Designer.
In Administration:
Click the Application tab.
The Web Report Designer subsection will appear. Click on it to open it.
Overview of Terminology
Below is what your web-based Report Designer will look like. Underneath, we break down each function's name and what it does!
Name | Function |
Design Surface: | Displays a report's structure and contents that are separated into bands. You can use the tools on the Report Designer's panels to design the report. |
Menu: | Used to manage and set up reports. |
Fields Panel: | Access the report's data source from Aspire. Each report was designed to pull specific fields from Aspire. Please use the Idea/Voting Portal if you would like to see new fields to a report dataset in a future release. |
Properties Panel: | Properties panel is used to set up the report controls. |
Report Design Analyzer: | Shows errors, warnings, and information messages. Helps users create or enhance a report layout. |
Report Explorer: | Access the report's elements or objects in the Report Explorer panel. Useful for locating a specific report bands or objects that are used from the Toolbox. |
Report Tab(s): | Displays report sessions that you have currently open. |
Toolbar: | Used to Copy, Cut, Paste, and Delete objects; Contains Full Screen and Zoom Controls. |
Toolbox: | Drop report controls (i.e. label, picture box, rich text) to the Design Surface |
What Report Types Can You Customize?
There are a total of 14 report types that you can customize the Web Report Designer! They are listed below from A to Z!
Report Type | Location |
Client Budget | Property |
Daily Timesheet | Schedule Board |
Deposit | Invoicing ➡️ Deposit ➡️ Deposit Record |
Employee Weekly Time Card | Weekly Time Review |
Equipment Inspection | Reports Module ➡️ Equipment Inspections [Role Permission] |
Invoice | Invoicing |
Invoice Statement | Invoicing ➡️ Receivables. |
Opportunity Estimate Sheet | Opportunity ➡️ Estimate |
Opportunity Proposal | Opportunity |
Opportunity Work Ticket Items | Reports ➡️ Work Ticket Item Sourcing |
Payment | Invoicing ➡️ Payments➡️Payment Record |
Quality Audit | Property |
Receipt | Purchasing |
Work Ticket | Work Tickets |
⚠️ If you want to customize these reports, you need to have specific user role permissions that are connected with the report.
Design Surface
The design surface displays a report's structure and contents that are separated into bands. You can use the tools on the Report Designer's panels to design the report. |
The Design Surface displays a report that is being edited.
Rulers
The horizontal and vertical rulers display tick marks in your report's specified measurement units. Click an element to evaluate its size and location using the rulers.
The horizontal ruler also allows you to modify the report's side margins (the report's Margins property value) by moving the left and right sliders on the ruler.
Report Bands
What is a Report Band?
A Report Band represents a specific area on the Design Surface that is used to define how to render the report controls that belong to it.
Report bands are represented by the parts of the Design Surface, which is divided with band strips.
Report Band Class Types
Below is a detailed example of all Report Band class types and a Band description:
Report Band Class | Description |
TopMarginBand | Located on the top margin of every page, above the PageHeaderBand or ReportHeaderBand. |
ReportHeaderBand | Located at the beginning of a report. It is intended to display some introductory information (i.e., a cover page) |
PageHeaderBand | Located at the top of every page, below the TopMarginBand or ReportHeaderBand. This band is intended to display page numbers or a table header, continued from the previous page. |
GroupHeaderBand | Located at the beginning of every group, or at the top of the group in case it is split across pages. This band specifies grouping criteria and is used to display information at the beginning of a group of records. |
DetailBand | Located on a page between all other bands. This band displays a single record from the bound data source at a time or simply holds unbound controls if there is no a data source assigned to a report. |
DetailReportBand | Located below the DetailBand and is intended to hold the detail report when creating a master-detail report. |
GroupFooterBand | Located at the end of every group, or on the bottom of the group in case it is split across pages. This band is mostly intended to show summary information for a group. |
ReportFooterBand | Located at the end of a report. This band is intended to display some final information, e.g., report totals. |
PageFooterBand | Located at the bottom of every page, below the BottomMarginBand or ReportFooterBand. This band is intended to display page numbers or a table footer, which has been continued on the following page. |
BottomMarginBand | Located at the bottom margin of every page, below the PageFooterBand. |
Sub-Band | A report band that provides a functional copy of the source band. It can be used to display different objects. |
You can select a band and click on the band's tab title to collapse or expand the band.
Report Band Selection (Properties Panel)
Here is how Report Bands selections are displayed in Web Report Designer:
Report Band Tasks
Except for Top and Bottom Margin Bands, each Report Band has a special Tasks menu to control the band’s behavior.
Top Margin Band
The Top Margin Band is located on the top of the Web Report Designer Design Session and on every report page.
The Top Margin Band is used to control the margin whitespace at the top of the report.
Standard Height Examples: 25, 50, 75, 100
This section repeats any control that is added from the Toolbox (i.e., PageInfo Control)
This Report Band does not have a Task Menu.
Report Header Band
If the Report Header Band is added to the Design Surface, it is located at the beginning of the report. (If adding at the Report Level)
At a Report level, the Report Header Band will show as “ReportHeader” or “ReportHeader1”
The Report Header Band is intended to display some introductory information (i.e., a cover page, company/branch logo, record number, etc.)
Separate Report Header Bands can be added at a Detail Report Band level.
Page Header Band
The Page Header Band is located at the top of every page, below the TopMarginBand or ReportHeaderBand.
This band is intended to display page numbers or other controls, continued from the previous page.
Group Header Band
The Group Header band is located at the beginning of every group, or at the top of the group in case it is split across pages.
This band specifies grouping criteria and is used to display information at the beginning of a group of records.
❗ NOTE: This is the most important Report Band to control because it groups your data.
If not grouped correctly, this will cause display issues.
What is the importance of the Group Fields section of the Group Header Tasks?
As the name suggests, GroupHeader Bands are designed to group data fields.
If you expand the Group Fields section, you should see the Group Fields option.
By clicking the ( + ) icon, Web Report Designer will add a new field value that has the Group By in the name.
When the field is created, you can select from a list of data fields related to the data member you have selected for that Detail Report Band.
If you continuing adding grouping criteria, additional fields Group Fields rows will appear that will have the Then By in the name.
Next to your grouping criteria, you should see an arrow icon either pointing up or down. This allows the Ascending or Descending display of data.
If you do not apply any grouping rules, then a GroupHeader Band will only display a single record. Please test grouping rules for proper data displays.
The best fields to use with Group Header Bands are fields that contain SortOrder or ID in the name.
If the Data Member list doesn’t have ID or SortOrder fields, then use a field that contains Name to group with. (Try testing the Group Fields section for proper displays)
Detail Band
The Detail Band is located on a page between all other bands.
This band displays a single record from the bound data source at a time.
You will always find a Detail Band at the Report Level and Detail Report Level (If the designer decides to add one)
Detail Report Band
The Detail Report Band is a band that can be set to display different data member content and house its own report bands.
Group Footer Band
The Group Footer band is located at the end of every group, or on the bottom of the group in case it is split across pages.
This band is mostly intended to show summary information for a group.
Report Footer Band
The Report Footer Band is located at the end of a report.
This band is intended to display some final information (i.e., report totals, report signatures)
Page Footer Band
The Page Footer Band is located at the bottom of every page, below the BottomMarginBand or ReportFooterBand.
This band is intended to display page numbers or a table footer, which has been continued on the following page.
Bottom Margin Band
The Bottom Margin Band is located on the bottom of the Web Report Designer Design Session and on every report page.
The Bottom Margin Band is used to control the margin whitespace at the top of the report.
Standard Height Examples: 25, 50, 75, 100.
Will repeat any control that is added from the Toolbox (i.e., PageInfo Control).
This Report Band does not have a Task Menu.
Sub-Band
A Sub-Band is a report band that provides a functional copy of the source band. It can be used to display different objects.
Data Members
Located in the side panel
Each report type is designed to pull specific fields from your Aspire System.
Not all fields are stored within one dataset or a single Data Member's table.
In Report Designer, you will see many Data Member options:
These Data Member options contain "spReport" in its naming convention.
Example: spReportOpportunityHeader, spReportOpportunityService, etc.
Please reference the Report Designer Available Fields spreadsheet for a full list of fields from each Data Member
🧠 Remember, Data Members will determine the fields that can be displayed for a Report Band.
Tip: Hover over the Data Member with your mouse to display the full name of that Data Member
Calculated Field
Using a Calculated Field (aka Calc Field) allows you to apply complex expressions to one or more data fields that are obtained from the report’s underlying data source in Aspire. Moreover, you can both group and sort your report data based on a calculated field’s value.
In order to create a Calculated Field, you need to select the Fields Panel:
Under the mdl_ReportType, you will see datasets that are designed for that report.
There will be a icon that will display a tool tip.
The tool tip will say Add calculated field
Calculated Field: Edit Mode
Report Designer will add your new Calculated Field using a default naming convention such as calculatedField1, calculatedField2, etc.
It is considered a best practice to use a custom name for your new Calculated Field.
If you select the pencil icon, you can drill into your Calculated Field to customize.
Calculated Field: Expression Editor
To create how the field is calculated, click the three dots in the Expression field.
In the Expression Editor, build your needed expression. You can use data fields, report parameters, predefined constants as well as various date-time, logical, math and string functions. Below are examples:
Calculated Field: Operators Guide
To help build your expressions, below is a guide with examples to show how data fields can be calculated in relationship to each other.
Arithmetic Operators | Example |
+ (Addition) | A + B |
- (Subtraction) | A - B |
* (Multiplication) | A * B |
/ (Division) | A / B |
% (Modulus or Modulo) | A % B |
Relational Operators | Example Description |
> | x > y (x is greater than y) |
< | x < y (x is less than y) |
>= | x>=y (x is greater than or equal to y) |
<= | x<=y (x is less than or equal to y) |
= | x==y (x is equal to y) |
!= or < > | x! = y or x <> (x is not equal to y) |
!< | x!< y (x is not less than y) |
!> | x!>y (x is not greater than y) |
Logical Operators |
In |
And |
Or |
Not |
Naming Conventions
Best practice for Report Designer is to use camelCase style but making sure you capitalize the first letter of the first word for clarity. camelCase: Starts off with a lowercase letter and with a capital letter in each corresponding word.
Example: CamelCase
There is an alternative called upper camel case (initial uppercase letter, also known as Pascal case)
Do not use:
⛔ kebab-case: In web development this is a popular style.
⛔ snake_case: Mostly a file name has a snake case naming style.
The same applies for Formatting Rules!
Field Types
Name | Description |
None | Indicates that the field’s type is undefined and determined by evaluating the actually returned object during report generation. Web Report Designer will try to figure out the field type depending on the expression used. Aspire recommends to keep all of your fields with a specific type to avoid any calculation issues. |
String | Indicates that the field returns a string value as a sequence of UTF-16 code units (the String type). UTF-16 is a character encoding capable of encoding all 1,112,064 valid code points of Unicode (Unicode is the standard used in the world's operating systems to support the use of text written). In other words, text that you type such as alpha/numeric symbols utilize what is called Unicode for other software to interpret that information. |
DateTime | Indicates that the field returns a value expressed as a date and time of day (the DateTime type). |
TimeSpan | Indicates that the field returns a value as a time interval (the TimeSpan type) |
Byte | Indicates that the field returns an 8-bit unsigned integer value. |
Int16 | Indicates that the field returns a 16-bit signed integer value (the Int16 type). [This is a non-decimal number] |
Int32 | Indicates that the field returns a 32-bit signed integer value (the Int32 type). [This is a non-decimal number] |
Float | Indicates that the field returns a single-precision floating-point value. |
Double | Indicates that the field returns a double-precision floating-point value. |
Decimal | Indicates that the field returns a decimal value. |
Boolean | A boolean or bool is a data type with two possible values: true or false |
The Decimal, Double, and Float variable types are different in the way that they store the numerical values. For example, a Double has twice the precision of a Float type (Numeric precision refers to the maximum number of digits that are present in the number). This means a Double is a stronger type if you are looking for precision-based accuracy with numerical data.
Formatting Rules
A Formatting Rule, also known as Conditional Formatting, allows you to change a report element’s appearance based on a True or False (Boolean) condition.
Boolean: A data type with two possible values: true or false. (Also known as Bool)
All report control objects (such as a label, picture box, table, table cell, rich text, or band) allow you to apply a Formatting Rule.
You can locate a Formatting Rule by selecting one of the following steps:
Properties Panel ➡️ Appearance ➡️ Formatting Rules
Report Explorer ➡️ Formatting Rules
Formatting Rules: Properties Panel
Expand the Formatting Rules section using the carrot icon on the left. This will display all the Formatting Rules created.
When viewing the Formatting Rules in the Properties Panel, Web Report Designer will allow you to do the following:
Add Rule
Delete Rule
Expand Rule
Select Rule
🧠 Whether you are adding, deleting, or sorting rules, remember that you can use the Undo and Redo buttons on the Toolbar.
The example provided in the image shows you that the BlankSpaceHide Formatting Rule is selected.
Using the carrot icon, we can expand that specific Formatting Rule’s sub menu which provides you many customization options.
Always use a strong camelCase style naming convention.
The Condition field is where you will insert a Boolean (True/False) expression.
This field has its own ellipsis where you can access the Condition Editor (like a Calc Field)
All Formatting Rules require an expression entered in the Condition field.
What is the main use of a Formatting Rule?
Most Formatting Rules consist of adding suppression (hiding or not visible) behavior.
The image below displays a Properties Panel field called Visible.
Setting the rule to True or False is what will trigger the behavior pattern based on the Condition field’s expression.
Formatting Rules: Report Explorer Panel
Expand the Formatting Rules section using the carrot icon on the left. This will display all the Formatting Rules created.
If you click on each rule, you will see a pencil icon to the left to edit the rule and a trash icon to the right to delete the rule.
⚠️ Caution: Deleting a rule (trashcan) will remove it from your list without prompting a confirmation window. If you accidently delete a rule, then you can use the Undo button on the Toolbar.
The same applies for deleted Calculated Fields on the Fields Panel.
Formatting Rules: Expression Editor
The Expression Editor window for a Formatting Rule may look like the Calculated Field’s Expression Editor, however, you must enter a True/False statement.
The example to the right shows the BlankSpaceHide Formatting Rule’s expression.
The expression IsNullorEmpty([ItemQuantity])
Translation: If the field called ItemQuantity does not have any data, then suppress (hide) the report element (band) or object (i.e., label, table cell, rich text)
Other Suppression Examples:
[OpportunityInvoiceType] != ‘Fixed Payment’
[ItemType] == ‘Labor’
[ItemType] in (‘Labor’, ‘Sub’, ‘Other’)
Filter Strings
The Filter String Editor provides a visual interface for constructing filter criteria with an unlimited number of filter conditions combined by logical operators.
Filter String Editor is available when you select a Detail Report and is located on the Properties Panel under Data.
The image below shows you that the ContractServices (Detail Report) Band was selected.
❗ Remember, when selecting at a DetailReport Band level, Report Designer will capture all bands within the Detail Report. This means that a DetailReport Band Class can have its own ReportHeader, GroupHeader, Detail, GroupFooter, ReportFooter Bands.
Filter Editor Window
When clicking on the Filter String's three dots, you will see a new window appear called the Filter Editor
The Filter Editor displays filter criteria as a tree where individual parts (nodes) specify simple filter conditions within the Detail Band you have selected.
To add a condition, you will need to select the + icon:
Remember, the Data Member you selected for the Filter String will display different fields.
Select the required data field from Aspire’s Data Member.
Now we're selecting an operator of Does not equal. The below image shows you the types of comparison operators you can select when building the filter.
Below shows a value box that allows you to insert an operand value
The value can be either a string or numeric
The example below shows zero “0” was entered.
In this example, we've set a filter to say "and Service Extended Price does not equal $0"
Using Multiple Filters
Multiple filters can be assigned to a Detail Band.
You can see how the complexity of layout behavior can increase based on multiple filters, as shown below.
Not only will the Filter String Editor display created filters at the top of the window, but below, you can select Advanced Mode to view each filter translated to expressions.
Explanation of additional filters:
ServiceOpportunityID Is not null: If there is no service than suppress the entire Detail Band
ItemType Does not equal Labor: If a client wants to suppress labor items, we can use this filter on making sure no labor items appear. The same can be applied to other item types such as Sub, Labor, Equipment, and/or Other.
ItemName Does not contain: You can suppress items via a naming convention. Let’s say a client does not want to show their customers any internal items such as “Fees”.
ServiceInvoiceType Does not equal Optional: Suppress any services that are added to the Optional Services group within the Aspire estimate. This is a useful filter that will keep the report from calculating Optional Services dollars into the total price.
Saving a Report
There are two options to consider when saving a report.
Saving a Current Version
When using this method, you will be able to keep your existing layout, and it will not create new versions of the document. Your report will lose the ability to revert any of the changes you have made.
To do this:
Open a layout from the Open Report option in the Menu.
Select Unpublish after report loads in the menu. This will have your current version set to unpublished status.
Apply your changes (save periodically)
Select Publish from the menu. This will keep the existing version with your updated changes.
PROS | CONS |
|
|
Saving a New Version
When using this method, a new version of your layout will be created. Previous versions of your report can be accessed, yet it is not great for minor changes.
To do this:
First, apply changes to the existing version.
Click the menu in the upper left corner. Select Save in the Menu. This will create a new version of your report.
The report will automatically be in unpublished status. Apply your changes (save periodically)
Select Publish when you are done.
PROS | CONS |
|
|
Copying an Existing Report
You will first need to locate and open the report you want to make a copy of.
Next navigate to the Menu in the upper left corner and select Save As
Insert a name in the Report Name field and select from the Branch list that allows access to this new report.
Click Save to finish.
Additional Resources
You may not learn everything there is to know about Web Report Designer in this article, but we want to also share links to additional documentation hosted by our backend report developer: DevExpress, and share a downloadable sheet for Written Expressions.
Documentation for Written Expressions
Download the attachment below if you need additional resources for Written Expressions when working with Web Report Designer.