Provides access to information from external data sources such as web services, or databases, leveraging the existing Dynamic Content Integration (DCI) infrastructure.
A data source component references a file containing a DCI template and defines a set of parameters, some of which are provided by the server and some by the client. When a data source component is created, the fixed, encrypted values are embedded in the JavaScript code that constructs the component and are stored inside the component. When the client requests the data from the data source, the data source makes a request to the server, passing all the information the server needs. The server then decrypts and converts the request into an appropriate server-side representation. Finally, it applies the referenced template definition to the set of parameters and returns the data. The output from a template definition must be a block of JSON XML representation, wrapped in a json:response element. The markup is processed into JSON syntax and sent to the client.
Refer to the topics entitled About DCI and About templates for more information about DCI and templates.
n/a
This component is provided by the cf2:data-source element. Its href attribute references a DCI template definition. The element can contain any number of parameters specified using cf2:param elements. The cf2:param elements define a combination of parameters that are common to all usages of a data source and those that are provided by the client to the fetch() method for a specific request. Those parameters that have a value specified using the value attributes are common to all usages of the data source, those that do not are expected to be provided by the client.
The following table presents the constraints that apply to the cf2:param attributes. Each parameter can have only one value. It is an error if a value is passed to the fetch() method for one of the parameters that already has a value specified in a value attribute. If none of the value attributes are specified, the value for the parameter will be provided on the call to the fetch() method. The type attribute can be used to ensure that the client provides the correct type of values for each parameter.
| Value attribute | Is the type attribute required? | Is the path attribute required? |
|---|---|---|
| boolean | No. It is treated as if it was set to boolean and it is an error if it is specified with any other value. | No. It is an error if specified. |
| number | No. It is treated as if it was set to number and it is an error if it is specified with any other value. | No. It is an error if specified. |
| string | No. it is treated as if it was set to string and it is an error if it is specified with any other value. | No. It is an error if specified. |
| component | Yes | Yes |
| property-value | Yes | No; although can be specified if necessary. |
| no value attribute | Yes | No. It is an error if specified. |
The property attribute is not supported.
This component supports the following method:
Makes an asynchronous request to the server to apply the template definition specified in the href attribute of the cf2:data-source element to the set of parameters and their values that were either provided in the cf2:data-source definition, or in the parameters Map inside the options.
| Parameter | Description | Type |
|---|---|---|
| options | A set of options. | Map |
The supported options are:
| Name | Description | Type |
|---|---|---|
| parameters | The map of parameters provided by the client. The value passed in for the parameters must satisfy both the type and usage constraints specified on the parameters. If they do not, then it is an error and an exception will be thrown on the client. If the client does not need to provide any parameters, then this is optional, or could be set to null, or an empty Map. | Map |
| onSuccess | The function to be called when the data has been fetched successfully. It takes a single argument of type cf2:dataSourceSuccess. It is an error if this parameter is not provided. | Function |
| onFailure | The function o be called if fetching operation failed. It takes a single argument of type cf2:dataSourceFailure. It is an error if this parameter is not provided. | Function |
The request sent to the server includes all the information necessary to apply the template, namely:
The base URL of the originating document.
The reference to the template definition.
The values of the fixed parameters (boolean, number, string) defined in the cf2:data-source definition.
The execution values of the dynamic parameters (component, property-value, path) defined in the cf2:data-source definition.
The values of the parameters provided in the parameters Map.
The first 3 items are provided by the server and are only needed by the server and therefore they will be encrypted.
Please note that it is possible that a single data source component could have multiple outstanding fetch requests in process at once. It is the responsibility of the custom JavaScript code to ensure that the resulting behavior is valid for a given application.
Whenever a request to fetch data from a data source succeeds, an instance of the cf2:dataSourceSuccess event is created and passed to the onSuccess callback function.
| Property | Description | Type |
|---|---|---|
| target | The data source from which the data were fetched. | DataSource |
| data | The data that were fetched. | any |
Whenever a request to fetch data from a data source fails, an instance of the cf2:dataSourceFailure event is created and passed to the onFailure callback function.
| Property | Description | Type |
|---|---|---|
| target | The data source from which the data were fetched. | DataSource |
| status | The status code indicating why the request failed. These will use and have the same meaning as HTTP status codes, even though the request to fetch data may not have been via a HTTP request. | int |
| message | A message describing the details of the problem. | String |
In order to minimize the chance that a client can use this mechanism to gain access to internal data the information that trips to the server and back to the client is encrypted and decrypted on the server using a private key that is configured in the client-round-trip-encryption element in the mcs-config.xml file. In addition, any attempt to access a local file that is either outside the webapp directory in which MCS is running, or inside its WEB-INF directory will cause an error. Please note that if a template definition is remote, no checking can be performed.
The previous steps are intended to protect the information provided from the server. If the data provided by the client also needs protecting, then the original page must be requested using https. In that case the data source will also use a secure encrypted transport protocol to send requests back to the server.
The security configuration, in particular the password, is stored in plain text within the mcs-config.xml file. It is expected that environment specific mechanisms will be used to limit access to that file. However, knowing the configuration is not sufficient to crack the security as there is a hard coded salt value in the code that is combined with the other configuration to create the key. Please note that changing any of the security configuration will cause all existing data sources embedded in the client to stop working.
The data source servlet is implemented by the com.volantis.mcs.servlet.cf2.DataSourceServlet class and by default is mapped to the webapp context relative path /cf2-data-source. The mapping for the servlet can be changed but doing so requires changing the servlet-mapping and providing a context parameter mcs.cf2-data-source.servlet.prefix which must match the value used in the servlet-mapping.