This page outlines the new features introduced into Impact for displaying repeating data in Impact report templates.

Current Limitations

The currently implemented report templates are designed to provide areas for drawing layers and data being displayed from fixed tables such as CUSTOMER, DRAWINGS, LAYERS and extra layer tables.

These report templates are limited to single page generation, although it is possible to use a report template settings to merge multiple pages into a single report.

It is also not easy to display repeating data in the current report templates without reverting to managing a number of text entities and filling them via scripting.

Consider, for example, a typical report template to show palette lengths used in a layer. Typically, text entities for each palette name and system text/script to calculate the length would be added to the report template. So, even if a particular palette isn’t used, it is still displayed, and adding a new palette requires modifying all report templates.

With the new child table data rows that can be attached to various tables in Impact it will not currently be easy to output this information on report templates without a large amount of scripting.

Existing Reporting Tools

While there are reporting tools available such as Crystal Reports or SQL Server Reporting they have several limitations.

• External reporting tools cannot easily be integrated into our existing report templates for displaying drawing areas or scripted text values.
• Crystal Reports requires expensive licensing.
• SQL Server Reporting is DB specific and doesn’t work with Oracle or MySQL.
• Data reports cannot easily be shared with all Impact customers.

Repeating Data

These new features in Impact provide a mechanism for generating repeating data using various sources and then easily displaying that data on report templates.

The repeating data can be shown on its own page, much like a traditional data report as generated using Crystal Reports or SQL Server Reporting. Alternatively, the repeating data can be mixed with existing drawing areas or text entities on a report template.

The repeating data will also flow onto multiple pages if it cannot fit on a single page. So there is no need to determine ahead of time how many data rows will be required in a report template.

The following sub-sections describe the use of Data Repeaters in detail:

Data Connectors
Provided Data Connectors
Testing Data Connectors
Data Connector Arguments
Report Templates
Report Groups
Data Text Entities
Report Template Settings
Running Data Reports

A new concept of a data connector has been implemented in Impact. Data connectors provide a way for data to be structured so it can be consumed by the new features in report templates for displaying multiple rows of data.

Data connectors provide an extensible mechanism allowing Impact to provide built-in data connectors, but also for data connectors to be written using VBScript and in future with COM interfaces.

Data connectors can be as simple as a list of layer names, extract data from a child table, retrieve a list of related Impact documents or, in fact, provide any repeated data generated from a script.

The data provided by a data connector is structured and typed so that it can easily be consumed and formatted using the familiar tools available in report templates.

Data Connector Arguments

Each data connector can have one or more arguments that can be passed to the data connector for controlling what data it loads.

Most data connectors will require an Impact drawing or layer from which to retrieve the appropriate data.

You will see later on:-

• When testing data connectors that the data connector will automatically be assigned the current drawing layer.
• When configuring report templates that the data connector will automatically be assigned the drawing layer that has been assigned to a report template area.

So, typically, you only need to configure additional required arguments for each data connector.

The following data connectors have been implemented.

Arden.ChildTableDataConnector

This data connector provides child data rows attached to a parent Impact project.

You must specify the table relationship key in the required Relationship argument. The Database Installation ->Table Relationships page now has a handy Copy Key button to make this easier.

You can use table relationships where the parent is one of CUSTOMER, SITES, DRAWINGS, LAYERS, ONE_UP, MULTI_UP etc.

Arden.DocumentsDataConnector

This data connector provides a list of documents related to an Impact project.

An optional Relationship argument can limit the documents retrieved.

Arden.IDatabaseQueryDataConnector

This data connector can be used to query almost any data in the Impact database.

This data connector uses the recently added IDatabaseQuery interface to provide a read-only view of data in the database.

Use the OnCreateScript argument to specify VBScript to return an IDatabaseQuery object to the data connector.

For example, this script creates an IDatabaseQuery object for querying all USERS in the database. Note, you should assign a TableName so that the IDatabaseQuery can load all the required column types and lengths.

' IDatabaseQuery Data Connector script example
' 
' The Impact/NServer, ActiveDatabase, ActiveDrawing, ActiveLayer variables
' are available but may be set to nothing.

set query = ActiveDatabase.Connection.CreateQuery
 
query.TableName = "USERS"
query.SQL = "select * from USERS"
set Result = query

Internally, the data connector will use the IDatabaseQuery to run the query and retrieve the rows.

Arden.PalettesUsedDataConnector

This data connector provides a simple list of palettes and palette lengths used in a project layer.

This shows how a simple data connector can be used to display all palettes and their lengths in a report template with very little effort. 

As already mentioned, previously you would need to create multiple text entities within the report template. With this data connector the palette list is dynamic and it only shows those palettes actually used in the layer. Also, no changes are required to the report template if new palettes are used in a project.

You can limit the palette types returned by this data connector using the PaletteTypes argument. Valid arguments are as follows:- Balance_Knife, Crease, Cut, Cut_Crease, Delamination, Laser, Matrix, Milling, Non_Print, Other, Perf, Profile_Rubber, Rev_Crease, Rev_Score, Rubber, Score, Secondary, Strip_Knife.

Arden.ProjectLayersDataConnector

This data connector provides a list of layers in a project including all LAYERS database values.

The LayerType argument can be used to limit the layers returned, in which case database values from the layer type will also be available.

Arden.ProjectRevisionsDataConnector

This data connector provides a full list of project revisions for a project.

The project must have previously been saved in the database.

Arden.VBScriptDataConnector

This data connector is a powerful fully customisable data connector that can be used to provide ANY structured repeating data.

The required DataConnectorScript argument provides four functions within the script and the data connector automatically calls these methods at the appropriate time.

An example is shown below. In this example Connect and Disconnect aren’t used.

' VBScript Data Connector script example
' 
' The following functions are used by the VBScriptDataConnector to retrieve
' columns and rows from your data connector. You can define global variables
' and use them from any code, or create useful functions for use in
' the data connector.
' 
' The four predefined functions below are called during various stages of
' the data connector. You can use these functions for any required purpose. ' The Connect/Disconnect methods could be used to connect to an external 
' data source for example.
'
' The Impact/NServer, ActiveDatabase, ActiveDrawing, ActiveLayer variables 
' are available but may be set to nothing. To support adding text entities 
' you should ensure that GetColumns works without being connected and 
' without an ActiveDrawing.

Function Connect
Connect = True
End Function

Function Disconnect
Disconnect = True
End Function

Function GetColumns
' define 4 columns
Dim columns(3, 2)

' a character column of length 20
columns(0, 0) = "Name"
columns(0, 1) = dctCharacter
columns(0, 2) = 20

' an integer column
columns(1, 0) = "Count"
columns(1, 1) = dctInteger
' a distance column
columns(2, 0) = "Distance"
columns(2, 1) = dctDistance

' a boolean column
columns(3, 0) = "Ticked"
columns(3, 1) = dctBoolean

GetColumns = columns
End Function

Function GetRows
' return 2 rows of data (with 4 columns)
Dim rows(1, 3)

rows(0, 0) = "Fred"
rows(0, 1) = 20
rows(0, 2) = 25.4 ' must be internal units
rows(0, 3) = True

rows(1, 0) = "Mary"
rows(1, 1) = 0
rows(1, 2) = 100
rows(1, 3) = False

GetRows = rows
End Function

The VBScriptDataConnector is currently the most powerful data connector and can be used to return virtually any repeating data for display in a report template.

Arden.XmlDataConnector

This connector provides a convenient way to generate xml data so it can be consumed by a data connector. It would be useful if you have some repeating data that doesn’t change often that you want to display on a report template.

The xml can be specified as a string argument or using an external .xml file.

To load picture (image) values into xml you need to convert the binary data into base64 strings. You can do this programmatically, or using an online web service such as https://www.base64-image.de/

The XmlDataConnector has been used in most of the example report templates because it allows the repeating data to be stored within the report template itself, rather than rely on some external source.

The XmlDataConnector is not currently Unicode compatible. String values are always converted to the active Windows code page.

<<Data Connectors 

Impact provides a built in mechanism for displaying and testing available data connectors.

If you are designing a report template and you want to show repeating data on that report then you can easily test the data connector before configuring it within the report template.

To do this you should open a project that would serve as a good example containing the data you want to output on the report template. For example, if you want to display related child data on a report template, then open a project containing that child data.

Testing a data connector in this way does not change the project, it’s just automatically used as a source for the data connector.

Registered Data Connectors

Open the Database Administration form and select the Database Installation -> Data Connectors page. This page shows all registered and available data connectors.

Each data connector has a unique name (including a namespace such as ‘Arden’).

A short description and the log level (see below) of each data connector is also shown.

Selecting a data connector shows the available arguments below the list view.

Data Connector Logging

Rather than a single global logging level, each registered data connector can be configured with its own logging level.

This is useful if you have report templates using multiple data connectors and you just want to generate logging from one particular type.

Logging levels are stored in the database installation settings and can be pushed to Site databases with Enterprise publishing of Installation Options.

Testing a Data Connector

After selecting a registered data connector on the Database Installation -> Data Connectors page press the Test button or double click the data connector.

The Data Connector Test form is displayed and has three panels:-

• The top panel shows the data connector and configured arguments and the log level for the test run.
• The middle panel shows rows returned by the data connector when it is tested. This will show all retrieved columns, data rows and values generated by the data connector.
• The bottom panel shows any logging messages from the data connector. This is useful to track down issues or missing arguments. The log panel will be hidden if the log level is set to none.

The Connect and Read Data button will test the data connector by connecting to the data source, retrieving data columns and data rows. The test form will read data in chunks of 100 rows, so if more data is available a Load More Rows button will become available.

For example, testing the Arden.DocumentsDataConnector with an open project containing linked documents will produce results as below. 

The log shows details of all the retrieved data columns including their names, types and lengths.

The 36 rows retrieved from the data connector are shown in the middle panel.

The test form allows you to configure any required or optional arguments for the selected data connector. Click the Arguments button to open the Data Connector Arguments form.

<<Provided Data Connectors 

The Data Connector Arguments form allows you to configure required and optional arguments. 

The form shows the valid arguments, which could be a mixture of required and optional arguments.

• Arguments are separated by semi-colons.
• Arguments separated by a vertical bar mean only one of those arguments can be specified.
• Optional arguments are surrounded by square brackets
• Argument values separated by a vertical bar mean only one of those values can be specified
• Argument values separated by commas mean one or more values can be specified

Enter any arguments directly in the list.

Test the data connector to verify that the arguments are valid.

Argument Editors

The arguments list has some special editors built in (using the editor button in the value column).

• When an argument expects a script then the VBScript inline editor form is shown.
• When an argument expects xml then the Impact text editor form is shown.
• When an argument expects a file path then the file selector form is shown.

Copying/Pasting Arguments

The form supports copying and pasting of all arguments in a single operation using the copy/paste buttons shown below the arguments list.

<<Testing Data Connectors 

This section describes how to configure a report template for displaying repeating data from a data connector.

There are several example templates that you can examine to see how these work to produce multi-page data reports.

Report Page Size

The first thing you should do when designing a report template that will be used with repeating data rows is define the page size.

You do this using the sheet size in the layer properties; the Sheet and Edges / Board pages are now available in one-up layers within Template drawings. Previously they were only available for manufacturing layers.

For an A4 Portrait report template set the sheet size to 210 x 297 mm with all margins (edges) set to 5 mm. This defines the usable page area – it is important to set the margins as many printers cannot print to the whole page. The usable page area is also used to determine the minimum view extents when printing.

You should use an origin position of 0.00mm, 0.00mm.

You should also turn on the sheet in the visibility options as it makes designing your report template easier.

Common Sheet Sizes

There are MTS available for common printed sheet sizes that can easily be used to create report template pages.

<<Data Connector Arguments 

Report Groups are the building blocks of data reports. If you have ever designed reports in Crystal Reports or SQL Server Reports then you should be familiar with the concept.

The difference is that in Impact you use blocks to design report groups.

Typically, start designing a report group by drawing a simple rectangle representing the size of the report group in the report template. Then create a block from the rectangle.

Report Group Inspector Page

The Report Group entity inspector page is available for an individually selected block within a template drawing. You can then turn the block into a report group by checking the Is a report group checkbox.

Report Group Types

There are 5 available report group types:-

Data Repeater Report Group

A Data Repeater report group must be added to the report template; this is the primary report group that determines how repeated data should be generated and displayed.

Currently only a single Data Repeater report group can be used within each Template drawing, but this may change in the future.

Report Area

The Data Repeater report group should be associated with a report template drawing area within the report template. The report template drawing area can either be visible or invisible.

When the data report is generated the layer assigned to the report area will automatically be assigned to the data connector. This allows the data connector to load data appropriate for the assigned layer or project.

Using a report template drawing area to associate a layer means that the existing layer matching rules can be used when running the data report.

Data Connector

Choose a registered data connector from the drop down list.

You can then set appropriate arguments for the data connector. You can paste arguments that you have set up while testing the data connector.

By assigning a data connector to a report group the drawing layer from the associated report template drawing area will automatically be assigned to the data connector.

Associating Report Groups

Each report group is associated with other report groups by setting the same Report Area.

So, for example, to associate a Data Header report group set the same report area as the Data Repeater report group.

Report Group Size

Typically you need to define a fixed size for each Report Group. This is done using the extents of the block that you are using for the report group.

You need to do this because text entities used within the report group will not produce a consistent size as they may resize based on their contents. Also, you may wish to have some margins around the text entities within the report group.

If you want to have a border around the report group then simply add entities such as lines or a rectangle to represent the border. The border will be duplicated for each report group.

If you don’t want a border you should still use entities to represent the group size then set the Construction Palette for the report group to match the palette of those entities. When the report group is used it will first calculate the extents and then delete all construction entities.

You should ensure that any entities that you want to keep do NOT use the construction palette.

Report Group Origin

You MUST set the block origin of any report group block to the bottom left corner of the block. Failure to do so will prevent the data report from being generated.

Report Group Block Insert Origin

The location of report groups block inserts in the report template layer is also important. The x-axis of all report groups is never altered and is used to locate all groups as they are generated.

Typically, placing the page headers/footers at the top and bottom of the usable page area (within the page margins) makes sense.

The position of the data repeater or optional data header defines where the first data row will be placed on the first page of the data report. On the second and subsequent data pages the data header and data rows are always started from the top of the page.

If you want to mix both traditional page areas and or database text entities, you should place the data repeater (or optional data header) in the correct vertical position on the first page. The remaining vertical space on the page will be used before data rows flow onto subsequent pages.

Sub-Blocks

You can set blocks within a block to be report groups, but they will be ignored when generating any data report. All report group blocks should be created in the layer rather than within any sub-blocks.

Current Block and Selected Entities

When running the report template a couple of extra things now happen:-

• If the template has been left with a block active the current block is automatically changed to the layer block. This may produce unexpected results if there are any changes in the block that have not been saved, as this process discards any changes.
• If any entities are selected in the template layer then they are automatically deselected.

Both these operations are noted in the debug.log.

<<Report Templates 

Once you have assigned a data connector to the report group block any text entities that you create within that block can display data from the data connector.

Make the report group block current and create any required text entities. You should try and place text entities with the report group size you defined earlier.

Typically, you would want to use bounded text entities within report groups so that text fields don’t overlap.

The Text Editor will automatically show the data connector in the database table combo; you can then add any columns from the data connector directly into text entities. You can also use the formatting options for column types that support it.

It is also possible to add text entities that use image (picture) columns within report groups. Using an image within a text entity will paint the image as the background of the text entity.

For some data connectors it may not be possible to show the available columns, in which case you will need to add them manually. However, you will not be able to apply formatting in this case.

Multi-Page Data Reports

The power of data reports is their ability to automatically generate multiple pages if the repeating data cannot all fit on a single page.

The report template generator automatically keeps track of the number of rows that can be displayed, including calculating spaces for page headers and footers, and data headers and footers.

When it detects that a new page is required, it automatically creates a new page and continues displaying data rows from the top of the new page.

Lookups in data repeater rows

Each DataConnector can return an optional table name for each data row which can be used as the child table for lookup values. The following DataConnectors can be used with lookup values:

If a table relationship ONE_UP.OU_INT->SALESREP.SR_KEY exists and the data connector is returning ONE_UP data then

[$DATA.OU_INT->SALESREP.SR_FULLNME]

can be used, where SR_FULLNME is the displayed column. The display column can be any type (including picture), and can be formatted using the Text editor form if required.

If you want to use LAYERS columns then you should qualify them as

[$DATA.LAYERS.L_STATUS->PLSTATUS.ST_STATUS]

<<Report Groups 

Not much has changed in the Report Template MTS.

Simply add your new template containing one or more report groups as a page in the Report Template MTS.

When displaying a template for the report page, if the template contains a report group then the background sheet is automatically shown and used as the initial zoom extents.

This doesn’t happen in the Impact Browser when viewing a data report template.

Multi-Page Report Settings

So, with a combination of the existing Report Template MTS pages and the new data reports, it’s possible to generate reports containing multiple pages with varying content.

For example, you could create a Report Template MTS containing pages for:-

• Cover Page using database text entities.
• Manufacturing Layer Page, using drawing area, database text entities and PalettesUsedDataConnector.
• 3D Layer Page, using drawing area.
• Documents Page, using a DocumentsDataConnector.
• Revisions Page, using a RevisionsDataConnector.

<<Data Text Entities 

Data reports are run using the existing Report Templates mechanism.

This includes using the existing built-in layer matching for matching layers from a drawing to report template areas.

Send to New Project

The easiest way to test data reports is to send them to a new project (from the Report Template MTS).

This will create a new layer for each report page.

In addition, the page size from the report template is copied into the destination layer and used automatically when viewing the report pages.

This means that when switching between report pages or zooming to the extents the page size is considered to be the minimum extents.

Send to New Layer

When sending a report template to the current project and creating new layers another small change has been made. Previously, the last layer produced from a report template was automatically selected; now it is the first layer produced.

Send to Printer

The same page size is also used when generating printed reports. This ensures that data pages that don’t have entities that extend to the outer extents of the page will print correctly.

Previously report templates generated without a page size would be centred in the printed page rather than placed at the top of the page.

<<Report Template Settings