1

Report Designer

From Resco's Wiki
Jump to navigation Jump to search
Mobile reports
Resco Academy
Resco Academy has a course on a similar subject:

Report Designer is a tool available to CRM administrators that allows you to design custom mobile report templates. The template is then saved in your CRM as a record and it can be used across all mobile projects in your organization.

If you don't want to use the designer, you can create or edit the report templates directly as XML files.

Tip This article introduces the concepts and basic functions of the Report Designer. To jump into action, check out also the Report Designer examples. For questionnaire reports, see Mobile reports for Resco Inspections.

Accessing the designer

Report Designer can be started from the management console of your CRM:

  1. Using a web browser, log in to your CRM.
  2. Launch the designer:

Using the designer

On start, the Report Designer shows a list of existing reports. Use the toolbar in the top part of the screen to access most functions.

Report designer main screen (list of reports)

New
Create a new report. Specify a name, select an entity, the language, and decide if you want a report for a single record, for multiple records, or a combination.
Edit
Select an existing report and open it for editing.
Properties
Select a report and modify its properties.
Delete
Delete selected report.
Activate
Active reports are available in the app.
Deactivate
Inactive reports are not available in the app.
Import
Upload an XML file with a report.
Export
Download a copy of the select report template to your computer as a file in XML format.
Clone
Create a duplicate of the selected report template.

You can use the Search field above the toolbar to filter your reports. To sort the reports, click the header row of the report list.

Creating a report

create a mobile report dialog

Click New and provide the following details:

  • Enter a unique name for the report. The name is used to identify the report in the designer and also in the app.
  • Select an entity as the primary variable. The data of this entity can be used in the report. However, you can link other entities to add additional information to the report.
  • Select the language of your report. The app only displays reports that match the language of the app, and the universal language-neutral reports.
  • Select a source: decide if you want a report for a single record, for multiple records, or a combination. Again, this may impact if your report is displayed in the app, for example, single-record reports are not available when you use multi-selection in views.

Editing a report

A new report contains a header block, a footer block, and a grid block.

  • Use the toolbar buttons to add or remove grids, cells, columns, repeating blocks, and images / signature.
  • Left pane displays a list of fields and variables you can add to your report. Drag them to the report.
  • Use the right pane to modify the properties of selected items.

Once you've done editing a report, save changes and remember to activate it to make it available in the app.

report desiger editor screen

Structure

Mobile reports are a collection of a few elements:

  • Text blocks and image blocks define the data to display.
  • The Grid element is used to arrange the blocks.
  • The Repeater element allows iterating over a collection of CRM records (contained in the primary variable or fetch variables).

Grid

Grid is the basic container element of a mobile report. It contains blocks of text and/or images arranged into a table pattern.

Click Add Grid to place a new grid. Grids can be added to the top level of your report, or into a Repeater element. New grids are added just after the currently selected element. Use the buttons Up and Down to move them around.

Each grid starts with a single empty cell. Double-click the grid and use the plus buttons to add columns and rows to your grid.

sample grid in report designer

Column width

The maximum width of the grid is equal to the width of the page. You can specify the width of columns either by dragging or by setting Width on the Properties pane. You can enter either fixed width (in pixels) or flexible width (as a fraction of the total width).

Report designer: column resizing

If the grid contains at least one column with flexible width, the width of the grid is set to the page width. To calculate the width of flexible columns, we subtract all fixed-width columns from the page width and distribute the remainder evenly. To increase the width of a flexible column, increase its width in fractions. For example, a 2-fractions wide column is twice as wide as a 1-fraction column.

Report designer: column width properties pane

In the example above, the first column is 100 pixels wide, and the remaining space is divided between columns 2 and 3, with column 2 being twice as wide as column 3.

Row height

Rows start with the default, automatic height that adjusts to the size of the content of the cell. You can modify the height either by dragging or on the Properties pane. Clear Auto height to disable automatic height calculation and enter explicit pixel size (Exact height).

Report designer: row height properties pane

The automatic calculation uses the maximal height of the blocks in the grid row. That means either the height of text in a particular font or the height of an image (the image height might be scaled automatically to fit into a particular width).

Parent grid

A parent grid essentially behaves just like a regular grid, with the additional function that you must select a related entity. All fields of the related entity become available in the entire report. This is similar to defining an additional fetch variable using the Edit Sources button, but you don't have to write the fetch.

Header and footer

Header and footer elements are essentially very similar to grids, with the following exceptions:

  • They repeat on each page of the report
  • They cannot be deleted from the report (but they can be empty)

Text block

The purpose of the text block is to display textual data. This can be either data from your organization or simply static text.

Click Add Cell to add a text block to your report. A text block can be placed into any grid, or into the header or footer.

You can configure the behavior of your text block on the Properties pane.

  • Column and Row define the position of the block in the grid (starting with 1, 1 for the top left corner).
  • Col. span and Row span define the spanning of the block across multiple columns or rows. Default values: 1. The actual pixel size of a text block depends on the properties of the grid.
  • Style and Visibility control if and how the text is displayed
  • Binding Type defines how the cell should be interpreted:
    • Constant is used to display text verbatim, for example, for labels.
    • Value is used to display dynamic data.
    • Raw Value is used when you need to access the internal value of a field, for example, the internal number of an option in an option set.
  • Borders allow you to set up custom borders for the cell. Default borders are defined using styles.

Dynamic data

Drag a field from the left pane directly to the text cell. This binding can be the name of a primitive (input) variable, such as dateRange. It can also be the name of a composite (primary, fetch) variable and a particular field, for example: order.totalamount.

To display multiple variables in a single field, wrap their names in curly brackets: {order.street1}, {order.city}, {order.country}. Any text outside brackets will be copied verbatim (as a constant).

Formatting

If you need to format a numeric or date value in a certain way, add a colon and a formatting string after the variable name: {order.createdon:YYYY-MM-DD}. Please see the C# Visual Studio reference for the possible formats.

You can optionally include also the culture identifier to format dates or numbers for a specific culture. This controls the names of months, separators, etc.: {order.createdon:YYYY-MM-DD;lang=en-US}. Examples:

  • To convert the decimal variable to currency, use this C# format in the binding field – {variableName:C}.
  • To convert DateTime variable to date variable, use this C# format in the binding field – {variableName:MMMM d yyyy}.
  • To display a floating-point number with a regional decimal separator and two digits after the separator, use {variableName:0.##;lang=sk-SK}.

See also formatting strings in rules for more examples of using format strings.

Image block

The purpose of image blocks is to display JPEG or PNG images. Their size and position follow the same rule as the text block. Click Add Image to add it into any grid, header, or footer.

Static images are loaded from the Offline HTML section. Set Binding type to "Constant" and as Binding, enter the image path: folder/name.png or folder/name.jpg.

Dynamic images are loaded from note attachment or cloud documents. To select the image, set Binding type to "Value" and click the Binding to define a fetch filter for the note entity. Remember that you can also use other variables in place of filter condition values.

The size of the image displayed depends on the selected size type:

  • Fit to Cell: image size depends on the grid cell's properties. The width is always calculated based on the width of the column. The height of the image is then adjusted based on the width-to-height ratio.
  • Custom: image size depends on specified Width and Height (lower value applies) directly in the image properties. The aspect ratio is always preserved, and images are never upscaled.

See also Report Designer examples.

QR codes

You can generate QR codes from report data. Click Add QR code to add it to your report. You can configure it on the Properties pane:

  • QR Code Type: Use Default for universal use; or switch to Pay by square to generate a payment order compatible with bysquare.com.
  • Binding: Enter either static text (Hello world), a value from the report ({contact.name}), or a combination (https://{account.website}/).
  • ECC level - error correction makes code more readable when it is distorted due to dirt, damage, or fuzziness. Higher level adds more redundancy at the cost of using more space. Default value is 7%.
  • Pixels per module - The more pixels per module (PPM), the larger the image.

Additional notes and limitations

  • QR codes are handled like a special type of images, hence the same features, formatting options, and limitations apply.
  • In version 14.2, QR codes are not supported when reports are generated from the web interface or in mobile report preview.

Signatures

We offer multiple ways how to display signatures on your reports. Click Add Signature to add a signature block into your grid, header, or footer.

See Adding signatures to reports for more information.

Repeater

Thanks to the repeater element, you can display a list of multiple records in your reports. The element consists of an optional header grid element and a body. If the repeater spans multiple pages, the header is repeated on each page. The body of the repeater may contain a single or multiple grid elements. You can also nest one or several repeater elements into the report.

The repeater inherits all variables defined for the report, this means, all fields available on the parent level are also available for the child. It also contains one special iteration fetch variable. The repeater body is rendered for every record from this query. This example uses a repeater to list all contacts related to an account.

Increase the Instances per row property if you want to place multiple instances of the repeater in one row. By default, each instance starts in a new line.

Child repeater

A child repeater essentially behaves just like a repeater, with the additional function that you must select a related entity from a list when creating the repeater. This saves you the hassle of defining the fetch variable using the Edit Sources button.

Visibility

By default, blocks that you add to your report are visible, unless they are empty. For example, if you add "City" to your report but the record does not have city defined, no city is displayed. In fact, if "City" is the only field on a report row, the entire row is skipped (unless you define a fixed row height, see above).

You can control the visibility of a text block, image block, or grid, by setting the Visibility property on the Properties pane. The value used must be a valid variable in curly braces, e.g. {customer.primarycontactid}. The block or grid is hidden when the variable is false, zero (0), or null (empty). If you need the opposite behavior, use the exclamation mark before the variable: !{customer.primarycontactid}.

To see this in action, see the cell visibility example.

An advanced tip that uses visibility: You can add multiple blocks to a single cell. Normally, these would simply overlap, for example, you could see two texts superimposed in the same space. However, you can use conditional visibility to display only the appropriate text block. Use the overlapping cells indicator and selector to select the right cell and set its properties.

Report designer: Overlapping cells indicator and selector

Page breaks and row breaks

To keep your report organized, you can force a page break before a block:

  • Use Page Break on the Properties pane to force a page break unconditionally.
  • Use Keep Together on the Properties pane of a grid to force a page break if at least one line of the grid does not fit on the current page. Available for PDF output.

The Break rows property serves a different purpose.

  • When enabled (default setting), multi-line text rows can be split into two pages. Only applies to text rows with automatic height. Fixed height cells and images are never broken.
  • Clear this property to ensure that rows stay on one page. (A cell may be still split if it does not fit to one page.)

Note: Page breaks within repeaters are not supported when using Microsoft Word as your report output format.

Preview reports

Once your report is drafted in the designer, you can preview it. Click Preview Report in the toolbar to display the report in PDF format. If the report has required variables, you can set these up using the Set Preview Variables button. The option to Preview Report is only available in Resco Cloud.

Editing styles

Click Edit Styles while editing a report template to customize cell styles. Unlike styles in Woodford where the styles are shared across an entire app project, styles in the Report Designer are unique per report.

See Style editor for more information. Check out also an example that uses a custom barcode font to display product barcode on a report.

Edit sources

Mobile reports contain text, numbers, and images. This data can be static or loaded from the database. When you're creating a report, you must decide about the primary variable of your report: either a single record or a collection of records. However, sometimes you might need additional variables in your report.

Note If the primary variable is a collection of records that is the result of a multi-select command, the primary variable fetch is never really run, and therefore, the fetch properties such as filter or sort are ignored.

Click Edit Sources to define the additional variables:

  • Primitive variables: string, decimal number, boolean, date and time
  • Complex variables: fetch result, fetch table, fetch table lookup

Once defined, the variables are listed in the left pane in a dedicated section. Drag them to the report as needed.

Variables can be defined on the root level or repeater level. Root variables can be used in the entire report; variables defined on the repeater level are only available for use in that repeater.

Primitive variables

The simplest use case is reuse. For example, if you need to use the same static text or number on several locations of your report, you can define an appropriate variable and add it to the report multiple times as needed. If you later need to update this value, you simply change it once in the variable definition.

Variables can be used to perform arithmetic or string operations. See an example how to use variables to multiply data and display them in your report.

For a repeater block, you can use variables, for example, to number the individual instances of the repeater. See automatic numbering for inspiration.

Complex variables

Complex variables involve FetchXML to retrieve additional data for your report. Often, you need to display data from a related entity; for example, on an Account report, you might want to display related contacts.

You have to define a data filter to get the records that you need. In the filters, you can use other variables in place of filter condition values.

Another aspect of complex variables is that they are not a single value, but often an array of multiple values. We use the dot notation to access the values, for example, myContact.name.

In some cases, adding a parent grid to your report can serve as a simpler alternative to defining a fetch variable using the Edit Sources button.

Fetch variable

This variable represents a single record loaded via fetch. If the fetch returns more than one record, the rest is discarded.

  • Click Edit to specify fetch conditions.
  • To use other previously defined variables as parameters in the condition, use the Set Variable button.
  • If you need the last or first record, use the Sort button.

By default, all attributes are returned. To access the entity attributes, use the dot notation (as can be seen in the Fields pane on the left).

Use fetch variables if you need to show attributes of a related record on the report, or the record is needed for a calculation.

Fetch Table variable

This variable represents a lookup table, i.e., a key-value pair.

  • Values are the records returned by the fetch query.
  • The key is the value of entity property defined as the LookupKey. In general, you would use the logical id, name, or a group-by alias.

When to use: This feature is an optimization, it allows to load multiple records in one query execution. Then each record can be accessed via the Fetch Table Lookup variable.

The Aggregates button allows defining aggregation and grouping attributes for a Fetch Table variable. If aggregate or group by attributes are set, only these are returned (not all attributes). Please note that alias is mandatory and you might want to use it for the Fetch Table key.

Fetch Table Lookup variable

This variable retrieves a record loaded into a Fetch Table. It has two parameters:

  • Table name: this is the name of a previously defined Fetch Table variable.
  • Index name: this binding defines the value of the key for the lookup. This can be static text, or use curly braces for a value lookup.

Built-in variables

Report Designer also comes with a few built-in variables, predefined for your convenience.

  • The PageNumber variable (Page: {PageNumber}) specifies the sequence order of each page.
  • The PageCount defines the total number of pages that the report contains.
  • The CurrentDate variable ({CurrentDate:DDDD}) enables you to add the date and exact time when the mobile report was generated.
  • The RowIndex variable applies to repeaters and contains the row number. To use it, add {<entity>Index} to a field; for example, {contactIndex} if you're in a repeater that lists contacts.

For example, in the footer (or elsewhere on the page) you could include {PageNumber}/{PageCount}, dynamically changing depending on the page the user is viewing at that moment.

Input variables

Sometimes, you want to allow users that they specify a certain parameter at run time, for example, a date range of the report.

  1. Select the report body and click Edit Sources.
  2. Add a variable and check Visible to make it visible as an input parameter when generating the report.

Report designer: Input variables: From to parameter

Add business logic

Just like many other content tools available on the Resco platform, Report Designer also supports rules that can add some business logic to your reports. In the case of the Report Designer, whenever a new report is created, or a new instance of a repeating block is created, this triggers an On Create event. You can define steps that should be performed when such an event happens. For reports, the steps don't allow you to control the user interface (enable or disable a field, show or hide something, etc.); you can only assign values to variables or perform arithmetic operations. (Variables can be used to hide a portion of the report indirectly; see Visibility.)

To define the steps, proceed as follows:

  1. Select either the report body or a repeater.
  2. Click Edit Sources to display a list of variables defined for that component.
  3. Select any variable and click On Create to display the rules editor.
  4. Use the usual Rules editor syntax to define one or more steps that should be performed.
  5. Remember to save all changes.

Tips:

  • On Create is not available for "Fetch" type variables. Fetches query data from the database, it does not make sense to define On Create steps for those.
  • To keep things organized, the steps are defined per variable. However, all steps defined for variables on the same level of hierarchy run together, in a sequence.
  • Steps are executed in the same order as the order of the variables in the list. You can use the Up and Down buttons to change the order of variables.
  • If you first define var1, then in the steps of var2 you can utilize var1. However, using var2 in the steps of var1 would not be possible.
  • Often, it makes sense to initialize variables on the parent level and then perform additional operations on the child level.

Report Designer examples include several use cases where you can see the On Create rule in action.

JavaScript

Resco JavaScript Bridge can be used to extend the no-code functionality of mobile reports. For example:

  • Show or hide a (custom) command related to reports.
  • Define the behavior of a custom command related to reports.
  • Automatically run a report in certain conditions.
  • Perform an additional action (e.g., create an email message).
  • Modify report's XML source. You can even skip Report Designer, define the entire report in JavaScript code, and then run it.

Technical information

Behind the scenes, the definitions of mobile reports are stored in a custom entity called "resco_mobilereport". The actual structure is saved in the field Body (resco_data) in XML format.

See also



Was this information helpful? How can we improve?