Search

 

Concerns: Vision

User: User Management Site, Developer

Prerequisites

- Installation Futurama Vision Management Site

- Installation Futurama Vision Database

- Usage of the Futurama Website edition

Introduction

Within Futurama web applications it is possible to store personal preferences of users of the web application and retreive data that is stored. This page describes the configuration needed to store data from a Futurama application in Vision.

 

Description

Using the Futurama Website edition, it can be necessary to store information from a user. For example if you have created a website where your users can log in to see personal financial information. At this website you probably have some input fields. In some situations you want to give your users the possibility to store the information they give in these input fields, to retreive this information in a next visit. The ensures that users don't have to fill in the same information in each new session. Another example is if you want to store some personal preferences of your users ('I want to receive e-mail notifications', or 'I wantthe website displayed with a large font-size', etc.). This information can be used to communicate with your users based on their personal preferences.

In order to store (and retrieve) information you must configure in the Futurama Vision Management Site what the structure of the data is to be stored. Information of this configuration can be found at this page. Furthermore, in your Futurama Document, where you define your application, you must define which personal data has to be stored at which moment. Also you have to define at which page of your application which data has to be retreived. Information how this can be defined can be found at the VisionReferences pages of DataStore.   

Overview

Using datastore allows a user to store data into Futurama Vision as a DataItem. These dataitems are contained in a collection called a DataSet, which all have to comply to a single data format, and this dataset can be configured to encrypt all data that is stored within.

This single format of a dataset is configured in a DataType, which consists of one or more versions. Every version is numbered and contains an XSD schema that describes the XML structure of all associated dataitems. A DataType's structure can be updated by adding a new version to this datatype.

Usage

This data consists of XML that must be constructed within a futurama application, and can be stored using the StoreData formula. This will store the data, but also a timestamp, an optional person-identifier and a small description.

Data can be retrieved by using the GetDataItems formula, which will return a list of ID codes, and the descriptions that were supplied while storing the items. This ID code can then be used to retrieve a single item using the formula GetDataItem.

DataItems and Persons

It is possible to connect a dataitem to a person, by supplying the StoreData formula with person's identifier. This also makes it easier to retrieve a persons dataitems by providing the persons identifier to the GetDataItems formula, to retrieve only the dataitems in a specific dataset for a single person. An example usage could be to store Scenario's for every user of a website in a single dataset, which would simplify the task of retrieving this information.

Example

First enter the DataStore definitionsmanagement page, and create a new datatype with a simple name and description (free to choose). A productgroup must also be selected, which will limit access to this datatype for Apps within this productgroup.

Then add a new (first version) for this dataset with a chosen versionname and description. The small xml example above can be used a sampleXML for this version. For the schema, the definition shown below can be used, while the target namespace MUST be set to "www.actuit.nl/test" for this definition.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.actuit.nl/testdata" elementFormDefault="qualified" attributeFormDefault="unqualified">
	<xs:element name="test">
		<xs:complextype>
			<xs:sequence>
				<xs:element type="xs:unsignedInt" name="id"/>
			</xs:sequence>
		</xs:complextype>
	</xs:element>
</xs:schema>

You have now created a fully functional datatype, and can now create a dataset in the DataStore contents management page. Here you can select the desired datatype, and the version you want this dataset to produce, and by which name this dataset must be accessible. After creating the dataset, you can use the Futurama formula StoreData to store XML data that adhere to the supplied schema tot the new dataset.

Updating datatype definitions

During the lifetime of a dataset, it might become desirable to make a small change to the definition of a datatype. This can be achieved by creating a new version within that dataset. In this dataset, the new schema can be supplied, but this also requires a conversion XSLT. This translation file will allow the conversion of dataitems with the previous schema, to the new schema. Below is an example of a newer schema for the example above which will add a name value to the rootnode, and will change the namespace. The second section of code below shows the required conversion XLST to convert any outdated dataitems to this newer version.

New xml schema (adds a name):

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.actuit.nl/testdata2" elementFormDefault="qualified" attributeFormDefault="unqualified">
	<xs:element name="test">
		<xs:complextype>
			<xs:sequence>
				<xs:element type="xs:unsignedInt" name="id"/>
				<xs:element type="xs:string" name="name"/>
			</xs:sequence>
		</xs:complextype>
	</xs:element>
</xs:schema>

The conversion XSLT:

<xsl:stylesheet exclude-result-prefixes="msxsl input" version="1.0" xmlns:input="http://www.actuit.nl/testdata" xmlns:msxsl="urn:schemas-microsoft-com:xslt" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
	<xsl:output indent="yes" method="xml"/>
	<xsl:template match="*">
		<test xmlns="http://www.actuit.nl/testdata2">
			<id>
				<xsl:value-of select="/input:test/input:id"/>
			</id>
			<name>unknown</name>
		</test>
	</xsl:template>
</xsl:stylesheet>

From this moment on, whenever an outdated dataitem is retrieved from the database, it is converted to the newer definition automatically, and stored that way. In the example mentioned above outdated dataitems will get automatically the name 'unknown'.

Hierarchy

It is possible to store dataitems in a hierarchical way, using the ParentID field when using the StoreData formula to store a dataitem. This parentID indicates the ID of the dataitem you want to connect to this particular dataitem. Multiple dataitems can have their parent set to the same single dataitem, thereby creating a tree-structure. This hierarchy does not limit itself to one layer, but dataitems can be linked indefinitely to form any hierarchy one could desire.

For example: A website's user has multiple configurations, each of which can contain multiple scenarios. This could be implemented by storing 2 dataitems with a configuration, and a number of scenarios in individual dataitems. The scenario items would then be connected to their respective configuration by supplying the ID of the configuration's dataitems as the ParentID of the scenarios' dataitems.

For efficient retrieval of a dataitems and all its descendants (and their descendants etc), it is possible to use the GetDataItemHierarchy formula. This simplifies the retrieval of a full hierarchical tree with only a single call.

Configuration Management Site

In the Futurama Vision Management Site two sections can be found for the configuration of the storing of data (definition management and contents management). These sections can be found in the menu 'Beheer'. See below for more information about the configuration in these sections.

Definitions management

When entering this screen, a list of existing datatypes is shown immediately. This list can be filtered by using the search filter in the top of the screen.

DataTypes

The form for adding or changing a datatype consists of the following elements:

  • Name: The name that identifies the datatype.
  • Description: A small description which illustrates the usage of this datatype.
  • Productgroup: The datatype will be available for apps within this productgroup, or other productgroups below this one.

The versions within a datatype can be shown by pressing the ">" button on the left side of every listing.

Datatype versions

A datatype version contains the following fields:

  • Version name: The name which uniquely identifies this version.
  • Description: A small description which illustrates the particular implementation of this version's structure.
  • XSD schema: The XML schema that defines the structure of a dataitem that adheres to this particular version.
  • Target namespace: The namespace for the XML of a dataitem, which should be mentioned as the targetnamespace in the earlier mentioned XSD schema. The validity of this target namespace will be compared to the one in the XSD.
  • Sample XML: This XML should be a small sample which conforms to the supplied XSD. This data is required for automatic validations, and should be kept as simple as possible.
  • Should this be any new version (version 2 or greater) for an existing datatype, then a conversion XSLT must be provided. This XSLT can update the existing dataitems that are still of the previous type, up to the new one. Should there be outdated dataitems with more than one version of difference, then it can be updated by applying the conversion XSLTs of the newer versions in sequence.

Note that in order to allow the user to fill in an XSD schema and a sample XML an exception has to be made in the configuration file of the Management Site for this type of input. See the paragraph 'Configuration file Management Site' for more information.

Contents management

When entering this screen, a list of existing datasets is shown immediately. This list can be filtered by using the search filter in the top of the screen.

Datasets

The fields that are contained within a dataset are:

  • ID: This read-only field is a unique identifier for this dataset.
  • Name: The name that uniquely identifies the dataset.
  • DataType: The datatype that all the items within this dataset should conform to.
  • Version: The version of the earlier mentioned datatype that this dataset should produce on retrieval of a dataitem.
    This means that should this dataset be set to a version 2 of a certain datatype, and it contain an outdated item of version 1, then upon retrieval of this item, it will be automatically updated to version 2 by using the defined XSLT in version 2, and stored in that manner.
  • Encrypted: By selecting this checkbox, all dataitems that will be stored in this dataset will be stored in an encrypted form. This will require the next two fields to be set in a correct manner:
  • Encryption key: The location in the Vision configuration file's appsettings section where the first encryption/decryptionkey code can be found.

Upon pressing the Save button, a validation will be performed on the made changes. An error will be shown if any problems have been found, and any corrections can be made afterwards by pressing the Back button of the browser.

Be aware that once a dataset contains dataitems, the encryption- and datatype settings cannot be changed, as this will have consequences for any contents of the dataset. See related topics for more info on data encryption.

Configuration file Management Site

In the section 'Definitions Management' you have to enter an XSD schema and a sample XML. In .NET this kind of input is default not allowed. This prevents the user to enter potentional dangerous script. In the configuration file of the Management Site you therefore have to make an exception for the 'Definitions Management' page. This exception you make by entering the code mentioned below within the configuration section of the configuration file.

<location path="Secure/Store/AdminDataTypes.aspx">
    <system.web>
        <httpRuntime requestValidationMode="2.0"/>
    </system.web>
</location>

The path 'Secure/Store/AdminDataTypes.aspx' is the page in the Management Site for which the exception has to be made.

Related Topics

- VisionReferences pages DataStore: Description how to use VisionReferences to incorporate storing of data in your Futurama Website application.

- Futurama Vision – Data : More information on data storage and data encryption in Futurama Vision.

External Links

- XML Schemas: More information about the structure of XSD files

- XSLT Tutorial: More information about writing XSLT files

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.

Updated: 2014-03-18