Changes in 5403211: Updated Izenda AdHoc Driver (markdown)

				Guides/Izenda-AdHoc-Driver.md
			
          @@ -68,11 +68,14 @@ The overridden fields can be seen in the Fields tab on the Report Designer after

           To override this method, simply add following method to the MyCustomDriver class:

           ```csharp

          -public override DataSet GetDataSet(IDbCommand Command)

          +public override DataSet GetDataSet(IDbCommand Command, Report report, string reportPart, string uniqueID)

           {

           DataSet result;

          -    result = base.GetDataSet(command); //If you want the driver to obtain DataSet and process it before returning

          +    result = base.GetDataSet(command, report, reportPart, uniqueID); //If you want the driver to obtain DataSet and process it before returning

          +    //do this only if you choose not to call the base.GetDataSet method

          +    //if (!string.IsNullOrEmpty(uniqueID))

          +    //    commandText = commandText.Replace(uniqueID, "");

               //result = new DataSet(); //If you want to implement your own method for obtaining a DataSet.

               //more processing....

          @@ -86,7 +89,7 @@ You can also see more coding examples [[here|http://wiki.izenda.us/API/CodeSampl

           The Izenda Fusion Driver composes data sources from several connections (data providers) into a single data source. This is very similar to how [[SSAS|http://technet.microsoft.com/en-us/library/ms175609(v=sql.90).aspx]] works, but using Fusion you can aggregate data not only from MSSQL databases but from very different data sources. For example, you can get data from the [[OData|Guides/OData]] data provider (i.e. without a direct connection to the database). All you need to do is set up the data sources' connections and you will be able to work with aggregated data as a single data source.

          -Currently, Izenda Fusion driver supports MSSQL, XML, ODATA, ORACLE, MYSQL, and PostgreSql

          +Currently, Izenda Fusion driver supports MSSQL, ODATA (via our [[custom ODATA provider|Guides/OData]]), Oracle, MySQL, and PostgreSql

           ###Configuring the Izenda Fusion Driver

          @@ -110,54 +113,33 @@ AdHocContext.Driver = fusionDriver;

           ####2. Add connections to the driver

          -Now you can add connections to the data sources end points. The end point could be a direct connection to the MSSQL database or it can be an OData connection to the MSSQL or Oracle database.

          -

          -#####a) Adding a direct and indirect database connection using the Fusion Driver:

          -

          -You can use the standard SqlServerConnectionString to connect to your database directly and also use the FusionDriver's capabilities to connect to an indirect database connection (like OData) at the same time:

          -

          -```csharp

          -AdHocSettings.SqlServerConnectionString = "my_first_connection_string";

          -Izenda.Fusion.FusionDriver.AddSqlConnection("SqlNW", @"my_second_connection_string");

          -Izenda.Fusion.FusionDriver.AddODataConnection("OD", @"http://...aspx");

          -```

          -

          -#####b) Adding multiple indirect data connections. 

          -

          -You can use the FusionDriver to add multiple indirect database connections to your Driver's context:

          +Now you can add connections to the data sources end points. The end point could be a direct connection to the desired database or it can be an OData connection using our provider. Below is an example of multiple connections being added to a single FusionDriver.

           ```csharp

          -<%@ Import Namespace = "Izenda.Fusion" %>

          -//Add the above to your Namespaces. Everything below should be placed within Initialize Reporting.

          -

          -//AdHocSettings.SqlServerConnectionString = "my_direct_connection_string";

          -//Use the above for direct connections

          -Izenda.Fusion.FusionDriver fd = new Izenda.Fusion.FusionDriver();

          -fd.AddConnection("SqlNW", Izenda.Fusion.FusionConnectionType.MsSql, @"http://url_to_sql_connector.com/provider_endpoint.aspx");

          +fd.AddConnection("SqlNW", Izenda.Fusion.FusionConnectionType.MsSql, @"YOUR_SQL_CONNECTION_STRING_HERE");

          +fd.AddConnection("OracleNW", Izenda.Fusion.FusionConnectionType.Oracle, @"YOUR_ORACLE_CONNECTION_STRING_HERE");

           fd.AddConnection("OD", Izenda.Fusion.FusionConnectionType.OData, @"http://url_to_odata_connector.com/provider_endpoint.aspx");

           fd.AddConnection("OD2", Izenda.Fusion.FusionConnectionType.OData, @"http://url_to_odata_2_connector.com/provider_endpoint.aspx");

           AdHocContext.Driver = fd;

           ```

          -####3. Set up additional settings

          +####3. Using VisibleDataSources and Constraints with Fusion

          -The Izenda Fusion Driver has several additional settings:

          +Two settings that function differently when using a FusionDriver are the VisibleDataSources and DatabaseSchema custom Constraints. Additional considerations need to be taken into account when using these settings.

           #####a) VisibleDataSources 

          -When using a FusionConnection with indirect database connections such as OData, the setup for VisibleDataSources is a little bit different. You will see an example below of setting up VisibleDataSources with indirect connections.

          +When using a FusionConnection with VisibleDataSources, it is necessary to specify which database your datasource is from using the alias provided for the specific connection when it was added to the FusionDriver.

           ```csharp

          -AdHocSettings.VisibleDataSources = new string[] { "Orders", "Customers", "Order Details" };

          -

          -fusionDriver.FixVisibleDataSources();

          +AdHocSettings.VisibleDataSources = new string[] { "SqlNW/Orders", "OracleNW/Customers", "OD/Order Details", "OD2/Products" };

           ```

          -_**Note:** This does NOT apply to direct database connections. However, calling FixVisibleDataSources with direct database connections will not have any adverse effects on your VisibleDataSources._

          +_**Note:** The only exception is when your connection uses a blank alias. Any tables in the VDS collection with no alias will be presumed as coming from the FusionConnection with the blank alias. If no such connection exists, then the datasource will not be available._

           #####b) Constraints

          -This is setup the same as for a single connection except that you are able to specify separate constraints for each connection by using connection aliases. Note that you can use wildcard characters to set up constraints:

          +Similarly to how the VDS collection works, constraints must use the alias of the database to which the datasource belongs. Joining across different connections is also a possibility, but will require additional considerations discussed [[below|http://wiki.izenda.us/Guides/Izenda-AdHoc-Driver#4.-Joining-datasources-from-different-databases]]

           **Example 1:** Static context

          @@ -192,6 +174,23 @@ You can configure the cache yourself by using the following properties and metho

           * **CacheReports method:** Indicates that all reports should or should not be cached (enabled by default in later versions of Izenda): ``AdHocSettings.CacheReports = true;``

           * **DataCache Interval:** Sets the number of seconds between cache refreshes. Example: ``AdHocSettings.DataCacheInterval = 60 * 24 * 30;``

          +####4. Joining datasources from different databases

          +

          +Using our Fusion Driver, it is possible to join datasources from different databases. This does require additional considerations when setting up the driver and adding connections. In order to implement this ability, the connections must adhere to the following conditions:

          +

          +* One connection MUST be given a blank alias. This connection will be used as the "default" connection through which queries will be routed.

          +* The default connection cannot be an ODATA connection.

          +* The default connection MUST use the same database as the type of FusionDriver being instantiated. The FusionDriver class is a MSSQL driver. Additionally there are the FusionDriverMySql, FusionDriverOracle, and FusionDriverPostgreSQL classes for the other supported database architectures. (e.g. if your default connection is using the FusionConnectionType of Oracle, your FusionDriver would need to be an instance of FusionDriverOracle)

          +

          +Below is an example of what a FusionDriver setup might look like that supports cross-database joining.

          +

          +```csharp

          +Izenda.Fusion.FusionDriverOracle myOracleFD = new Izenda.Fusion.FusionDriverOracle();

          +myOracleFD.AddConnection("", Izenda.Fusion.FusionConnectionType.Oracle, @"YOUR_ORACLE_CONNECTION_STRING_HERE");

          +myOracleFD.AddConnection("SQLDB", Izenda.Fusion.FusionConnectionType.MSSQL, @"YOUR_MSSQL_CONNECTION_STRING_HERE");

          +AdHocContext.Driver = myOracleFD;

          +```

          +

           ###Sample use

           Now that we have covered the basics of setting up the Fusion driver, below is a full example of how to set up and configure the Izenda Fusion Driver with several connections:

...	...	@@ -68,11 +68,14 @@ The overridden fields can be seen in the Fields tab on the Report Designer after
68	68	To override this method, simply add following method to the MyCustomDriver class:
69	69
70	70	```csharp
71		-public override DataSet GetDataSet(IDbCommand Command)
	71	+public override DataSet GetDataSet(IDbCommand Command, Report report, string reportPart, string uniqueID)
72	72	{
73	73	DataSet result;
74		- result = base.GetDataSet(command); //If you want the driver to obtain DataSet and process it before returning
	74	+ result = base.GetDataSet(command, report, reportPart, uniqueID); //If you want the driver to obtain DataSet and process it before returning
75	75
	76	+ //do this only if you choose not to call the base.GetDataSet method
	77	+ //if (!string.IsNullOrEmpty(uniqueID))
	78	+ // commandText = commandText.Replace(uniqueID, "");
76	79	//result = new DataSet(); //If you want to implement your own method for obtaining a DataSet.
77	80
78	81	//more processing....
...	...	@@ -86,7 +89,7 @@ You can also see more coding examples [[here\|http://wiki.izenda.us/API/CodeSampl
86	89
87	90	The Izenda Fusion Driver composes data sources from several connections (data providers) into a single data source. This is very similar to how [[SSAS\|http://technet.microsoft.com/en-us/library/ms175609(v=sql.90).aspx]] works, but using Fusion you can aggregate data not only from MSSQL databases but from very different data sources. For example, you can get data from the [[OData\|Guides/OData]] data provider (i.e. without a direct connection to the database). All you need to do is set up the data sources' connections and you will be able to work with aggregated data as a single data source.
88	91
89		-Currently, Izenda Fusion driver supports MSSQL, XML, ODATA, ORACLE, MYSQL, and PostgreSql
	92	+Currently, Izenda Fusion driver supports MSSQL, ODATA (via our [[custom ODATA provider\|Guides/OData]]), Oracle, MySQL, and PostgreSql
90	93
91	94
92	95	###Configuring the Izenda Fusion Driver
...	...	@@ -110,54 +113,33 @@ AdHocContext.Driver = fusionDriver;
110	113
111	114	####2. Add connections to the driver
112	115
113		-Now you can add connections to the data sources end points. The end point could be a direct connection to the MSSQL database or it can be an OData connection to the MSSQL or Oracle database.
114		-
115		-#####a) Adding a direct and indirect database connection using the Fusion Driver:
116		-
117		-You can use the standard SqlServerConnectionString to connect to your database directly and also use the FusionDriver's capabilities to connect to an indirect database connection (like OData) at the same time:
118		-
119		-```csharp
120		-AdHocSettings.SqlServerConnectionString = "my_first_connection_string";
121		-Izenda.Fusion.FusionDriver.AddSqlConnection("SqlNW", @"my_second_connection_string");
122		-Izenda.Fusion.FusionDriver.AddODataConnection("OD", @"http://...aspx");
123		-```
124		-
125		-#####b) Adding multiple indirect data connections.
126		-
127		-You can use the FusionDriver to add multiple indirect database connections to your Driver's context:
	116	+Now you can add connections to the data sources end points. The end point could be a direct connection to the desired database or it can be an OData connection using our provider. Below is an example of multiple connections being added to a single FusionDriver.
128	117
129	118	```csharp
130		-<%@ Import Namespace = "Izenda.Fusion" %>
131		-//Add the above to your Namespaces. Everything below should be placed within Initialize Reporting.
132		-
133		-//AdHocSettings.SqlServerConnectionString = "my_direct_connection_string";
134		-//Use the above for direct connections
135		-Izenda.Fusion.FusionDriver fd = new Izenda.Fusion.FusionDriver();
136		-fd.AddConnection("SqlNW", Izenda.Fusion.FusionConnectionType.MsSql, @"http://url_to_sql_connector.com/provider_endpoint.aspx");
	119	+fd.AddConnection("SqlNW", Izenda.Fusion.FusionConnectionType.MsSql, @"YOUR_SQL_CONNECTION_STRING_HERE");
	120	+fd.AddConnection("OracleNW", Izenda.Fusion.FusionConnectionType.Oracle, @"YOUR_ORACLE_CONNECTION_STRING_HERE");
137	121	fd.AddConnection("OD", Izenda.Fusion.FusionConnectionType.OData, @"http://url_to_odata_connector.com/provider_endpoint.aspx");
138	122	fd.AddConnection("OD2", Izenda.Fusion.FusionConnectionType.OData, @"http://url_to_odata_2_connector.com/provider_endpoint.aspx");
139	123	AdHocContext.Driver = fd;
140	124	```
141	125
142		-####3. Set up additional settings
	126	+####3. Using VisibleDataSources and Constraints with Fusion
143	127
144		-The Izenda Fusion Driver has several additional settings:
	128	+Two settings that function differently when using a FusionDriver are the VisibleDataSources and DatabaseSchema custom Constraints. Additional considerations need to be taken into account when using these settings.
145	129
146	130	#####a) VisibleDataSources
147	131
148		-When using a FusionConnection with indirect database connections such as OData, the setup for VisibleDataSources is a little bit different. You will see an example below of setting up VisibleDataSources with indirect connections.
	132	+When using a FusionConnection with VisibleDataSources, it is necessary to specify which database your datasource is from using the alias provided for the specific connection when it was added to the FusionDriver.
149	133
150	134	```csharp
151		-AdHocSettings.VisibleDataSources = new string[] { "Orders", "Customers", "Order Details" };
152		-
153		-fusionDriver.FixVisibleDataSources();
	135	+AdHocSettings.VisibleDataSources = new string[] { "SqlNW/Orders", "OracleNW/Customers", "OD/Order Details", "OD2/Products" };
154	136	```
155	137
156		-_Note: This does NOT apply to direct database connections. However, calling FixVisibleDataSources with direct database connections will not have any adverse effects on your VisibleDataSources._
	138	+_Note: The only exception is when your connection uses a blank alias. Any tables in the VDS collection with no alias will be presumed as coming from the FusionConnection with the blank alias. If no such connection exists, then the datasource will not be available._
157	139
158	140	#####b) Constraints
159	141
160		-This is setup the same as for a single connection except that you are able to specify separate constraints for each connection by using connection aliases. Note that you can use wildcard characters to set up constraints:
	142	+Similarly to how the VDS collection works, constraints must use the alias of the database to which the datasource belongs. Joining across different connections is also a possibility, but will require additional considerations discussed [[below\|http://wiki.izenda.us/Guides/Izenda-AdHoc-Driver#4.-Joining-datasources-from-different-databases]]
161	143
162	144	Example 1: Static context
163	145
...	...	@@ -192,6 +174,23 @@ You can configure the cache yourself by using the following properties and metho
192	174	* CacheReports method: Indicates that all reports should or should not be cached (enabled by default in later versions of Izenda): ``AdHocSettings.CacheReports = true;``
193	175	* DataCache Interval: Sets the number of seconds between cache refreshes. Example: ``AdHocSettings.DataCacheInterval = 60 * 24 * 30;``
194	176
	177	+####4. Joining datasources from different databases
	178	+
	179	+Using our Fusion Driver, it is possible to join datasources from different databases. This does require additional considerations when setting up the driver and adding connections. In order to implement this ability, the connections must adhere to the following conditions:
	180	+
	181	+* One connection MUST be given a blank alias. This connection will be used as the "default" connection through which queries will be routed.
	182	+* The default connection cannot be an ODATA connection.
	183	+* The default connection MUST use the same database as the type of FusionDriver being instantiated. The FusionDriver class is a MSSQL driver. Additionally there are the FusionDriverMySql, FusionDriverOracle, and FusionDriverPostgreSQL classes for the other supported database architectures. (e.g. if your default connection is using the FusionConnectionType of Oracle, your FusionDriver would need to be an instance of FusionDriverOracle)
	184	+
	185	+Below is an example of what a FusionDriver setup might look like that supports cross-database joining.
	186	+
	187	+```csharp
	188	+Izenda.Fusion.FusionDriverOracle myOracleFD = new Izenda.Fusion.FusionDriverOracle();
	189	+myOracleFD.AddConnection("", Izenda.Fusion.FusionConnectionType.Oracle, @"YOUR_ORACLE_CONNECTION_STRING_HERE");
	190	+myOracleFD.AddConnection("SQLDB", Izenda.Fusion.FusionConnectionType.MSSQL, @"YOUR_MSSQL_CONNECTION_STRING_HERE");
	191	+AdHocContext.Driver = myOracleFD;
	192	+```
	193	+
195	194	###Sample use
196	195
197	196	Now that we have covered the basics of setting up the Fusion driver, below is a full example of how to set up and configure the Izenda Fusion Driver with several connections: