Managing Data Sources

Each report must have at least one date source defined, with no name to be provided - it is treated as the default data source for the report and therefore it is mandatory. However, a report can be fed from more than one data sources - additional data sources can be added but each of them must be named.
For example, you can create the "Sales Order" report that would be populated from two data sources. The first one would be the order header object (acting as the default data source) and the other one would be a collection of order items (the additional data source named e.g. as "OrderItems").

When creating a report template (design time) you can provide information about data sources. To manage data sources open the "Data Sources Explorer" (click the "Data Sources" button on the Docentric Toolkit tab).

You can only bind tagging elements to the data sources defined in the template. For managing data sources the Data Sources Explorer pane is used. You can use the Data Sources Explorer to add a new and edit or remove an existing data source. Each data source must have a unique name.

Adding additional data sources

There is always a default data source defined on a template. You can't delete it nor you can change its name. This is because the report has no meaning without at least one data source. If you want to add additional data source, click the "Add" button in the "Data Sources" panel. The "Data Source" form will show up where you can set the name for the new data source.

After you enter a unique name you can click the "Ok" button to add the data source to the list. Similarly, you can edit an existing data source by pressing the "Edit" button. You can also remove an existing data source but the data source must not be a default data source nor used as a binding source by any tagging element in the template.

Data Source Kind

For each data source you can set the Kind property. You can set it to one of the following values: It can represent either a .Net object or an XML fragment/document

• .Net object: The data source will represent a .Net object.
• XML: The data source will represent an XML document or an XML fragment. This also means that at the report generation time the provided value for the data source will have to be a valid object containing an XML document. The object supplied as a value at the report generation time for the data source can be of one of the following types:
  • System.Xml.Linq.XDocument
  • System.Xml.Linq.XElement

Providing a schema for a data source

The Docentric Toolkit Add-In allows you to provide a schema for each data source defined on the report template. This is not a mandatory step but if you can provide schemas for the data sources, the Docentric Toolkit Add-In will be able to help you when doing data binding. You will also get additional help in terms of validations of data bindings especially when schama changes. Importing a schema is different for each data source kind:

• Importing a schema for a .Net Object data source
• Importing a schema for an XML data source
• Importing a schema for a DTS Object data source

Importing a schema for a .Net Object data source

There are couple of reasons why would you prefere .Net objects as data sources over XML for you report but the most important is the following: Your .Net application has already defined (domain) types in the DAL (Data Access Layer) in the form of DTO classes, or Entity classes in case you are using Entity Framework. In such case you will most often want to reuse such objects returned from the DAL to feed the reports.

The Docentric Toolkit Add-In allows you to specify any .NET type as a schema of a particular data source. For example, if you know that your default data source will be an object of type "Customer", then you can import the "Customer" class information as the data source schema.

To import a schema follow these steps:

• Open the Data Sources Explorer pane.
• From the data source list in Data Sources select the data source that you want to import the schema for.
• In the Schema info panel click the Import Schema button. This will bring up a file browser where you have to select the .NET assembly file containing the target .NET type.
• After the assembly selection the .NET Type Browser will show up. It shows namespaces and all public types of the selected assembly. Select the correct type and click the "Ok" button.
  
• If you want the currently selected data source to be a collection of objects of the selected .NET type, set the .Net Type Usage property to "As Collection". In this case the report engine will expect an object of type IEnumerable<Customer> and not Customer as a value for this data source.
  Make sure to always check the .Net Type Usage property. Invalid setting will always lead to errors.
• After the schema has been successfully imported, the .Net Member Tree panel shows the member tree of the imported .NET type.
  

Importing a schema for an XML data source

There are couple of reasons why would you decide to choose XML as data sources for you report:

• The document generation is a web service application that serves requests from different clinets that do not necessarily understand .Net. This is a perfect scenario to use XML as a data format to feed your reports.
• You do not have suitable .Net objects provided by your .Net application to be used as data sources for your reports. Or there are no DTOs at all because you use DataSets or DataTables hold the data retrieved from the database.

The Docentric Toolkit Add-In allows you to specify the schema for an XML data source in the following ways:

• Import the schama from an XSD file.
• Infer the schema from a sample XML file.

To import a schema follow these steps:

• Open the Data Sources Explorer pane.
• From the data source list in Data Sources select the data source that you want to import the schema for.
• In the Schema info panel click the Import schema from XSD button or the Infer schema from XML. This will bring up a file browser where you have to select the correct file (XSD or sample XML file).
• After the schema has been successfully imported, the XML Schema panel shows the schema of the imported XSD file or the schema inferred from a sample XML file.

Importing a schema for a DTS Object data source

The Docentric Toolkit Add-In allows you to:

• Import a DTS schema from any .NET type. The .NET type (including all dependent .NET types) are automatically converted to the corresponding DTS types (e.g. .NET Decimal converts to DTS Number, .NET Customer converts to DTS Complex type Customer)
• Load a DTS schema from a .dds file. The Load operation works in tandem with the Save operation.
• Save a DTS schema to a .dds file. Load/Save operations are usefull for scenarios where a development team wants to distribute schema changes to the other party (client or non-technical end users) without sending whole updated templates. The other party would then load the updated DTS schema file for the corresponding data source of the target template.

To import a DTS schema from a .NET type follow these steps:

• Open the Data Sources Explorer pane.
• From the data source list in Data Sources select a "DTS Object" data source that you want to import the schema for.
• In the Schema info panel click the Import Schema form .NET type button. This will bring up a file browser where you have to select the .NET assembly file containing the target .NET type.
• After the assembly selection the .NET Type Browser will show up. It shows namespaces and all public types of the selected assembly. Select the correct type and click the "Ok" button.
  
• If you want the currently selected data source to be a collection of objects of the selected .NET type, set the Type Usage property to "As List". In this case the report engine will expect an object of type List of Customer objects and not Customer as a value for this data source.
  Make sure to always check the Type Usage property. Invalid setting will always lead to errors.
• After the schema has been successfully imported, the Schema Member Tree panel shows the member tree of the imported DTS type (converted from the .NET type).