The Connection Manager makes creating new CAPS-Xt connections quick & easy; simply clicking the 'New Connection' button in the ribbon brings up the New Connection dialog.
From here, a new connection can be created from scratch, or an existing one can be copied. In general, we recommend creating a "base" connection that contains your connection string (or for a PROD solution, your web.config key) for a given external system, then copy it for all subsequent connections to that same system. When starting from scratch, the default options are:
Choosing any specifically named external system (i.e. SQL, Oracle, etc) will present a 'Connection String' section in which the necessary parameters of a connection string to that system will be presented in a series of inputs. If 'Custom' is selected, a simply text box will be presented to allow for entering/pasting of a complete connection string. Finally, choosing 'Web.config Key' will present an input for entering the name of the web.config key used to stored the connection string you wish to use.
In addition, all connections require selection of the connection Method (OLE DB or ODBC), require the specifying of a connection Name – which the service will enforce as unique, since it is used at runtime to tell the service which connection to run – and optional inputs for a Category, which can be used to filter the list of connections in the Connection Manager, and a Description, which is allows for & displays additional detail about that connection.
Next is the Command Type section; this is where a connection is configured to specify whether a query or stored procedure (for systems that support such a concept) call will be executed. An input is presented to allow for entering of the query itself or, in the case of a procedure call, the name of the procedure.
NOTE
While
the ‘Parameter Defaults’ section below provides the most control over what
parameters are passed as part of calling a connection (including the ability to
lock parameter values), you can also include placeholders in your Query or
Stored Procedure command text using the question mark ? character. At
runtime, when calling that connection, you would then simply pass in the
parameter name(s) and value(s) for each ? in your command text and the
Service will replace them automatically.
For
example, you could specify a Query such as:
SELECT TaskID, TaskTitle FROM
Tasks WHERE ProjectID = ? AND TaskStatus= ?
When calling this connection, you would then include the name-value pairs @ProjectID,13,@TaskStatus,Completed as part of your sqlParams and it would have the effect of filtering for Tasks where ProjectID=13 & TaskStatus=Completed
The next properties are optional and only need to be filled in as needed; the 'CorasWorks Variables Enabled' checkbox tells the service to check the parameters being sent into the call, including any URL to XSL (see next property) for any CorasWorks variables and, if found, use their value. Common uses of this include use of variables like [Me] in a query or procedure call, or use of a Global Variable or %SiteURL% in a URL to XSL.
The 'XSL Stylesheet' property is for specifying a URL to an XSL stylesheet that should be applied to the result of the service call. This file support XSL 2.0 and can be anywhere in the current web application as long as the user executing the call has Read rights to it. Alternatively, an XSL stylesheet can also be specified at runtime, so this is only necessary if you never want that connection to return un-transformed data.
Finally, an optional section of 'Parameter Defaults' is
included; any & all parameters here will be appended to the end of the
parameter collection (if any) sent through as part of your CAPS-Xt call. As many
optional parameters as you need can be added via the 
icon, and existing parameters can be
removed from the connection via the 
icon.
Each parameter listed also includes a 'Locked' 
or 'Unlocked' indicator 
. A locked parameter means whatever
parameter value is defined in the connection is the value that will be sent to
the external system by the service and there is no way to change or override it
at runtime. By contrast, an unlocked parameter can be overridden at runtime by
simply sending in the parameter with a new value; if absent from the call to the
service, the default value defined in the connection is used.
