Difference between revisions of "Connection Parameter Web Extension"

(Example 1: Simple mapping)
(Enforced mappings)
 
(3 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
== Installation ==
 
== Installation ==
 
* Place the {{Code|ConnectionParameterExtension.dll}} file into the Extensions folder of your XLCubed Web installation, usually at {{Code|C:\inetpub\wwwroot\XLCubedWeb\Extensions}}.
 
* Place the {{Code|ConnectionParameterExtension.dll}} file into the Extensions folder of your XLCubed Web installation, usually at {{Code|C:\inetpub\wwwroot\XLCubedWeb\Extensions}}.
* To ask XLCubed Web to load the extension, create the {{Code|InstalledExtensions.dll}} file in the same folder, with contents:
+
* To ask XLCubed Web to load the extension, create the {{Code|InstalledExtensions.xml}} file in the same folder, with contents:
 
     <?xml version="1.0" encoding="utf-8" ?>
 
     <?xml version="1.0" encoding="utf-8" ?>
 
     <installation>
 
     <installation>
Line 11: Line 11:
 
     </installation>
 
     </installation>
 
* Place the {{Code|mapping.xml}} configuration file into the same folder (see [[#Configuration|below]] for details).
 
* Place the {{Code|mapping.xml}} configuration file into the same folder (see [[#Configuration|below]] for details).
* Restart IIS or the Application Pool.
+
* Restart IIS or the Application Pool (also necessary after any configuration changes).
  
 
== Configuration ==
 
== Configuration ==
The {{Code|mapping.xml}} file contains the details of which [[Web Parameters]] should activate a mapping, and which server, database and cube details to apply to connections in the workbook as a result. Any blank details are left unchanged.
+
The {{Code|mapping.xml}} file contains the details of which [[Web Parameters]] should activate a mapping, and which server, database and cube details to apply to connections in the workbook as a result. Any blank details are left unchanged. An IISRESET or Application Pool recycle is necessary in order to reload after any configuration changes.
  
 
=== Example 1: Simple mapping ===
 
=== Example 1: Simple mapping ===
Line 20: Line 20:
 
     <parameterMappings>
 
     <parameterMappings>
 
       <parameter name="connection">
 
       <parameter name="connection">
         <mapping value="mapped" server="AlternativeServer.example.org" database="" cube="" />
+
         <mapping value="mapped" server="AlternativeServer" database="" cube="" />
 
       </parameter>
 
       </parameter>
 
     </parameterMappings>
 
     </parameterMappings>
  
The workbook would then use the connection details as published when loaded normally, but would connect to {{Code|AlternativeServer.example.org}} for its cube connections when loaded with a Web Parameter, for example:
+
The workbook would then use the connection details as published when loaded normally, but would connect to {{Code|AlternativeServer}} for its cube connections when loaded with a Web Parameter, for example:
 
     <nowiki>https://MyServer/XLCubedWeb/WebForm/ShowReport.aspx?rep=673dad1d-e406-4493-8ee3-6afdc9ec4f7f.wbsql&connection=mapped</nowiki>
 
     <nowiki>https://MyServer/XLCubedWeb/WebForm/ShowReport.aspx?rep=673dad1d-e406-4493-8ee3-6afdc9ec4f7f.wbsql&connection=mapped</nowiki>
  
Line 35: Line 35:
 
       </parameter>
 
       </parameter>
 
     </parameterMappings>
 
     </parameterMappings>
 +
 +
=== Example 3: Enforced mappings ===
 +
By default, if a parameter isn't used or a non-existent mapping value is chosen, the mapping is ignored and the original connection details are used. You can force the extension to enforce the mapping by using the following two attributes:
 +
; allowMissingParameter - 0 or 1 (default)
 +
: When set to 0, a value for the parameter must be given if the published report has a parameter with a matching name
 +
; allowUnknownParameterValue - 0 or 1 (default)
 +
: When set to 0, any given parameter value must be present in the list of mappings
 +
    <parameterMappings>
 +
      <parameter name="role" allowMissingParameter="0" allowUnknownParameterValue="0">
 +
        <mapping value="managers" server="" database="ManagerDatabase" cube="FullCube" />
 +
        <mapping value="users" server="" database="UserDatabase" cube="RestrictedCube" />
 +
      </parameter>
 +
    </parameterMappings>
 +
If these validation rules fail, access to the report is denied.
  
 
== See Also ==
 
== See Also ==

Latest revision as of 08:41, 10 July 2019

The Connection-Parameter mapping XLCubed Web extension allows XLCubed report designers to build Web Parameters into their reports that control certain Connection details.

Installation

  • Place the ConnectionParameterExtension.dll file into the Extensions folder of your XLCubed Web installation, usually at C:\inetpub\wwwroot\XLCubedWeb\Extensions.
  • To ask XLCubed Web to load the extension, create the InstalledExtensions.xml file in the same folder, with contents:
   <?xml version="1.0" encoding="utf-8" ?>
   <installation>
     <extensions>
       <extension source="RelativeFile" location="ConnectionParameterExtension.dll" />
     </extensions>
   </installation>
  • Place the mapping.xml configuration file into the same folder (see below for details).
  • Restart IIS or the Application Pool (also necessary after any configuration changes).

Configuration

The mapping.xml file contains the details of which Web Parameters should activate a mapping, and which server, database and cube details to apply to connections in the workbook as a result. Any blank details are left unchanged. An IISRESET or Application Pool recycle is necessary in order to reload after any configuration changes.

Example 1: Simple mapping

The simplest example would notice when a workbook was loaded with a Web Parameter (here, connection) set to a value (here, mapped):

   <parameterMappings>
     <parameter name="connection">
       <mapping value="mapped" server="AlternativeServer" database="" cube="" />
     </parameter>
   </parameterMappings>

The workbook would then use the connection details as published when loaded normally, but would connect to AlternativeServer for its cube connections when loaded with a Web Parameter, for example:

   https://MyServer/XLCubedWeb/WebForm/ShowReport.aspx?rep=673dad1d-e406-4493-8ee3-6afdc9ec4f7f.wbsql&connection=mapped

Example 2: Multiple mappings

You can configure the mapping.xml file to respond to multiple Web Parameter values. In this example, the role parameter can be set to managers to connect to one cube, and users for another:

   <parameterMappings>
     <parameter name="role">
       <mapping value="managers" server="" database="ManagerDatabase" cube="FullCube" />
       <mapping value="users" server="" database="UserDatabase" cube="RestrictedCube" />
     </parameter>
   </parameterMappings>

Example 3: Enforced mappings

By default, if a parameter isn't used or a non-existent mapping value is chosen, the mapping is ignored and the original connection details are used. You can force the extension to enforce the mapping by using the following two attributes:

allowMissingParameter - 0 or 1 (default)
When set to 0, a value for the parameter must be given if the published report has a parameter with a matching name
allowUnknownParameterValue - 0 or 1 (default)
When set to 0, any given parameter value must be present in the list of mappings
   <parameterMappings>
     <parameter name="role" allowMissingParameter="0" allowUnknownParameterValue="0">
       <mapping value="managers" server="" database="ManagerDatabase" cube="FullCube" />
       <mapping value="users" server="" database="UserDatabase" cube="RestrictedCube" />
     </parameter>
   </parameterMappings>

If these validation rules fail, access to the report is denied.

See Also