Being based on the SAGA standard OpenSAGA is fully compliant with the V-Model XT (the standard project management method for e-government applications in Germany). We are currently working on providing templates for jump starting V-Model XT based projects in connection with OpenSAGA.

Additionally OpenSAGA supports a highly agile, interactive and rapid prototyping based approach to application development. This approach is based on a top down view of the system to be build and starts from a high level perspective then chiseling out the details of your project. The whole approach is strictly model driven, so you first build the models and then refine them with more and more detailed submodels until finally getting to the code level where you actually implement the business logic either in Java code or one of the many scripting languages supported by OpenSAGA.

The examples in the reference manual will give you a brief overview about how we ideally start to approach projects with top down agility. Workshops and trainings are available to train you in this highly effective method that has been in use for many projects over the past eight years. Additionally the QuinScape GmbH provides courses on how to use V-Model XT in conjunction with OpenSAGA to the utmost effect - but never forget: You just need to start.

More details about the "OpenSAGA approach" are available in Chapter 4, Top Down Design and Development and more specifically in Chapter 6, Programming Tutorial: Developing a Web Based FAQ Application.

Although OpenSAGA models are abstract enough to also describe Swing or SWT applications we focus our development efforts on a single runtime platform - the web. We do this in order to increase our chances of providing a truly great platform as the support for a variety of platforms inevitably would lead to a lot of compromises and we do not want to compromise.

Accessibility is a complex technical topic and few web frameworks regard accessibility as a strategic topic. We are different in that we believe in supporting strong accessibility (e.g. even working completely without JavaScript support) as this is a common requirement in eGovernment applications. Nonetheless OpenSAGA includes strong support for modern web technologies including AJAX the major difference being that all OpenSAGA components take great care to include the full functionality for both JavaScript-enabled and -disabled environments.

OpenSAGA web applications are not very well suited to represent the functionality of classic content management systems (although there is some support for CMS functionality). OpenSAGA applications are better suited to presenting structured content, form based processes and complex workflow and work better with integrated CMS functionality (e.g. by retrieving content from the CMS and displaying it).

One of the major models of the OpenSAGA modeling ecosphere are the process models. Process models describe complex workflows made up from start states, view states, decision states, etc. and model the UI workflow for users. Additionally they offer various connection points to background processes.

Models are the core artifacts of OpenSAGA applications. As we believe in flexibility OpenSAGA offers a wide range of extension points which you can use to inject scripts or Java code into the models in order to exchange or enhance standard runtime behaviour. With this one exception models are the core unit of work and you will alter models in order to change behaviour.

OpenSAGA applications support both stages and extensions in order to compose complex application scenarios from simpler building blocks. Stages provide a means to separate infrastructure configuration details from the core functionality of a application and allow to define arbitrary sets of configuration data that e.g. differentiate between the settings of development, quality assurance (QA) and production settings. Additionally applications can be modularized in any way you like.

OpenSAGA additionally includes a composition feature that takes extensions with horizontal or vertical feature slices and combines them into powerful applications. As the developer is responsible for defining the boundaries of those extensions the mechanism is very powerful (and requires responsible behaviour) but can ultimately be used for various efficient architectures. For example it is possible to define a core layout for a global company in one extension and then specialize this core layout for subgroups and specialize them further down in extensions that inherit some behaviour of their parents, add new behaviours and modify existing behaviours. As the core extension mechanism is not limited to layouts but can be used for anything from single views to complex workflows highly complex and powerful configuration scenarios thus are easily supported.

OpenSAGA supports the latest stable version of Maven 2. We highly recommend the use of Maven 2.2.1 for OpenSAGA builds. Maven is distributed in several formats, you can download the recommended version from http://maven.apache.org/download. The use of Maven 3.0 is not completely tested so its use is inadvisable although Maven 3.0 supports a great backward compatibility.

The installation instructions can be found on http://maven.apache.org/download.html#Installation.

OpenSAGA offers its own Maven2 Repository. OpenSAGA M2 Repository doesn't proxy other repositories. So additional Dependencies can't be resolved by OpenSAGA M2 Repository.

This chapter describes the steps to achieve satisfied dependencies for OpenSAGA.

    <project xmlns="http://maven.apache.org/POM/4.0.0" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                                 http://maven.apache.org/maven-v4_0_0.xsd">
      <modelVersion>4.0.0</modelVersion>
      
      <groupId>${project.groupId}</groupId>
      <artifactId>${project.artifactId}</artifactId>
      <version>${project.initialVersion}</version>
      <packaging>war</packaging>
      
      <repositories>
        <repository>
            <id>opensaga</id>
            <url>http://www.opensaga.org/maven/content/groups/public</url>      
         </repository>
      </repositories>
      
      <dependencies>
        <dependency>
          <groupId>org.opensaga</groupId>
          <artifactId>core</artifactId>
          <version>${opensaga.version}</version>
        </dependency>
      </dependencies>
    </project>                
                    

mvn dependency:resolve

Our preferred IDE is Eclipse, especially since we provide a powerful plugin with OSclipse, which provides additional functionality while working with OpenSAGA in Eclipse (see http://www.opensaga.org/confluence/display/website/download-eclipse-plugin).

Configuring Eclipse for OpenSAGA Projects

We highly recommend that you download the OpenSAGA-Eclipse-Plugin since it provides extensive support for working with OpenSAGA (see http://www.opensaga.org/confluence/display/website/download-eclipse-plugin for details and documentation).

	Warning
	Be careful to correct configure Eclipse by defining the following specific settings: Disable auto reloading for your server. Usually this will cause endless loops and out of memory problems. Do so by double-clicking on the server, thus opening the server Next change to the modules tab and edit the OpenSAGA web module. Deactivate the auto-reload setting and press "OK".

OpenSAGA should work with any Java Application servers but often there are difficult problems with specific configuration settings. Below we summarize some of the most important configurations.

You have to specify a data source (the section called “The Data Source Model”) with the name portaldb. This is the default database used for all domain types, but you can define exceptions (see the attribute data-source-name in ???). If you don't specify your own database, a default HSQLDB database is used.

To run a OpenSAGA Portal without problems you should set the following parameters.

OpenSAGA offers two ways to configure the context path - either by defining the context parameter opensaga.CONTEXT_PATH in the web.xml or by setting the parameter context-path in the opensaga-project.cfg configuration file.

<context-param>
    <param-name>opensaga.CONTEXT_PATH</param-name>
    <param-value>/opensaga-core</param-value>
</context-param>

OpenSAGA installations use two variables to configure a project deployment. These can be either defined globally for all installations on the server or locally for each deployed project. Configuration settings are searched in the following order for each variable described below:

OPENSAGA_RESOURCE_EXTENSIONS=gis;sandbox;qs-dev
OPENSAGA_RESOURCE_EXTENSIONS_FOO=gis;sandbox;qs-dev

extensions=gis;sandbox;qs-dev

OPENSAGA_STAGES=global,dev-barney
OPENSAGA_STAGES_FOO=global,dev-homer

stages=global,dev-barney

Start programming. More details in Chapter 4, Top Down Design and Development.

Everything in OpenSAGA is a model. No exception. Except for implementations for various strategy interfaces used to extend the model. Clear about that :-) ?

We'll try again: The basic idea of OpenSAGA is that everything about your application is described by a model. Models are built in such a way that you can use them in an intentional declarative way. There are some exceptions - sometimes it makes no sense to describe a complex technological context with a model abstraction. An example for this are complex SQL statements. If you want to utilize the full power of an advanced database there is no better way than directly writing down tuned SQL statements. And those are the exceptions mentioned above: If it is necessary to write code directly OpenSAGA allows that - because for many cases code is the most appropriate form of modeling (at least it does not seem reasonable - except for syntactic sugar - that there might be a better DSL than SQL for retrieving data from relational databases). Thus everything in OpenSAGA is a model - only the syntax might differ at times.

All models in OpenSAGA for now are described by XML. XML was chosen for pragmatic reasons:

Each and every ID defined must be globally unique.

While every ID definition must be unique it is possible to reference one and the same ID in different contexts and receive different results. If e.g. a part model ID is referenced in a domain object reference the domain object governing the part will be retrieved. If the part model ID is referenced by some UI update mechanism it actually refers to the part (or rather: its HTML representation) causing it to update under specific conditions. There are many such examples explained in the specific contexts.

Global IDs consist of segments and usually will look very similar to Java package names (at least in the default implementation provided by the OpenSAGA base package). If a model ID contains either a dot '.' or a dash '-' it is a global ID and can be used unchanged. Additionally the IDs of top level tags always are global IDs.

All IDs that are not regarded as global are local IDs. Local IDs can be referenced with their local name within the current model file. Internally various strategies are used to convert local IDs to global IDs (usually by processing the DOM tree containing the XML model and prefixing the local ID with IDs from parent tags). Therefor local IDs can't be referenced from outside the current model file but are nonetheless a great way to reduce the amount of writing required when e.g. creating view models and linking content element models in those view models (e.g. linking labels to input models).

OpenSAGA differentiates a number of contexts with different scopes and lifetimes. Each scope can contain data in the form of atomic properties (of any property type defined in the system), objects (of a specific domain type) or lists of objects (of a single type).

The sections below explain the various scoped data contexts available in OpenSAGA applications. All share the following properties:

The following sections explains the layered scoped data context approach and their lifetimes.

Domain Context

The domain context is a supplementary context to the process context and shares its lifetime. The domain context is used to remember the object navigational path the user follows through the application.

Example 3.1. How a domain context path evolves

Example: The user starts on a view V-1 listing all employees of his company. He selects employee E-1 and examines the information about E-1 on view V-2. Then he clicks on the skill list of E-1 and examines the ratings ESR-1 on view S-3. The domain context path at this points contains a list of tuples containing (V-1, null), (V-2, E-1), (V-3, ESR-1).

The domain context contains all those objects in the so called domain context path. The individual objects can be accessed by referencing the ID of the corresponding view. Search starts with the last domain context path entry and proceeds to the first.

	Tip
	Actually the domain context path contains triplets consisting of the view passed, the primary domain object of that view (if one was defined) and the transition that was used to arrive at the given view. Since the transition is only used for internal purposes you usually do not need to know that.

See also the section called “The Domain Context Path” for more details about the domain context path.

The property reference resolving algorithm starts searching the property in the system domain object, then in the objects of the working set and finally in the target domain object. If the target domain object has been persisted at least once, the property is searched in objects that are related to the target domain object by to-one relations (assuming there are relation models defined for the domain type). If the target domain objecthas not yet been persisted the algorithm queries the domain context path for the property.

In OpenSAGA it is not possible to reference properties of cached objects or lists directly. It is necessary to define virtual properties. Virtual properties maps the real properties of an objects to a unique ID. So it is possible to reference the property of a special object. You can either specify virtual properties for the properties you want or expose all properties of the object with or without a prefix for the IDs.

The following example shows how to define a virtual property for a cached object.

<process-context>
    <scoped-domain-object id="cached.obj" domain-type-ref="type.a" name="dummy">
        <virtual-properties>
            <virtual-property id="cached.obj.name" property-ref="type.a.name"/>
        </virtual-properties>
    </scoped-domain-object>
</process-context>
    				

The following example shows how to expose properties of a cached object with a prefix

<process-context>
    <scoped-domain-object id="cached.obj" domain-type-ref="type.a" name="dummy">
        <virtual-properties expose-original-ids-of-domain-type-ref="type.a" 
                            exposed-id-prefix="foo"/>
    </scoped-domain-object>
</process-context>
    				

OpenSAGA provides object references that point to a list. For this case the contexts are not only searched for objects with the given id, but also for a list with this id. When a list with the id exists either in the context or is defined in the corresponding ContextModel, the list is used. When the list is not null and it has a current element, the resolver returns this current element, otherwise null is returned.

OpenSAGA provides object references that point to a view model (not a view state model!). If such a reference is to be resolved the corresponding view model will be searched in the current domain context path. If an entry for the given view model (via the view state model in the domain context path) is found, the corresponding root object for that view is returned. This allows to reference all view root objects of the current context.

We start with a bird's eye view of the application - the navigation model. The navigation model can be represented by a mind map that shows in a structured manner how the hierarchical organization of the web application should appear later on. When used in a moderated workshop it allows you to structure the requirements of the customer on a very high level and slowly form it into a master-detail-hierarchy that equals typical hierarchical navigation structures commonly used in web applications.

This kind of mind map then can be transformed directly into a navigation model as we will show.

The following mind map represents the rather trivial navigation for our FAQ web application:

Each node in a mind map can reference a process model indicating the process to be initiated when the navigation representation of the node is activated.

The process model for the FAQ application is a bit more involved, although not overly so. It contains the following elements:

The following process model represents these requirements:

Note that we do not say anything about permissions, etc. The roles allowed to execute certain transitions or able to access a state could be annotated at the respective transtions and states. For the sake of simplicity we omit this in this example, especially since the roles usually will be configured at runtime and only rarely belong to the static model.

Now that the overall scope and the main workflows have been specified we next define the domain. Domain modeling usually is a very complex and involved affair and a good domain model in the end probably is the most important factor in creating an application of lasting value. Usually we recommend reading Domain Driven Design by Eric Evans to get a better idea about how to model domains. Luckily this example is so trivial that the domain can be modelled trivially: We have one domain type (the FAQ entry) with two business properties (question and answer) as well as some kind of technical key.

Due to the trivial nature of the domain we omit an equally trivial UML class diagram.

First of all your new portal should know which new major elements (e.g. navigation models, domain type models and process models) will be an important part of the system. To achieve this we have to link the models (that we still need to write) from the portal meta model. The portal meta model always is contained in WEB-INF/resources/extensions/YOUR-EXTENSION-NAME/models/portal.xml. The meta model must contain references to the process model and the domain type model we are going to create in the next step. A correct declaration looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<portal id="portal.portal"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.pik.as/schema/model/portal-1.0.xsd">

	<domain-type-reference-set>
		<domain-type-reference domain-type-ref="faq.d_faq"/>
	</domain-type-reference-set>

	<process-reference-set>
		<process-reference process-ref="faq.p_faq"/>
	</process-reference-set>

</portal>

Since each model requires a unique ID we have identified our new domain type model specified in the section called “Modeling the Domain” with the ID faq.d_faq (according to the naming conventions explained in the section called “Model IDs”). In the same we we decided our single new process as specified in the section called “Modeling the Process” as faq.p_faq (obviously we named our extension as faq as you can derive from the prefixing rules explained under naming conventions).

Why references?

As we regard the XML representation of OpenSAGA models as but one representation (and e.g. serializing the data in database tables might be another viable and interesting option) you should regard these references as foreign keys and get accustomed to them. The OpenSAGA Eclipse plugin currently will warn you if you forget them and in a future version will automatically add them. So for now it's just a minor inconvenience.

In the section called “Modeling the Domain” we defined a single domain type we are going to use to store our FAQ question and answer pairs. The model for the domain type is straightforward. We need to define the model in a file called WEB-INF/resources/extensions/YOUR-EXTENSION-NAME/models/domain/types/d_faq.xml (again abiding by the naming extensions mentioned above and using the standard directory layout specified in the section called “Extension directory structure”).

A valid domain type model for our type might look like this:

<?xml version="1.0" encoding="UTF-8"?>
<domain-type xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.pik.as/schema/model/domain-type-1.0.xsd"
  id="faq.d_faq"
  name="faq">

  <property-set>
    <domain-type-property-set>
      <domain-type-property id="faq.d_faq.guid" name="guid" type="PlainText" 
                    insert-property-value-provider="guidPropertyValueProvider" />
      <domain-type-property id="faq.d_faq.question" name="question"
                    type="PlainText"/>
      <domain-type-property id="faq.d_faq.answer" name="answer" type="RichText"/>
    </domain-type-property-set>
  </property-set>

  <primary-key>	
    <key property-ref="faq.d_faq.guid"/>
  </primary-key>
</domain-type>

The meaning again should be pretty obvious:

Next we are going to model the process depicted in the section called “Modeling the Process”. Again this is pretty straightforward. The appropriate file according to the standard directory infrastructure and the naming conventions is WEB-INF/resources/extensions/YOUR-EXTENSION-NAME/models/processes/p_faq/p_faq.xml.

The content is the most extensive so far:

<?xml version="1.0" encoding="UTF-8"?>
<process id="faq.p_faq"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.pik.as/schema/model/process-1.0.xsd">

	<process-state-set>
	
		<!-- 
			============================================================ 
			===   Starts the FAQ application.                        ===
			============================================================
		-->

		<start-state state-ref="faq.p_faq.ss_start">
			<transition-list>
				<transition target-state-ref="faq.p_faq.vs_faq_list"/>
			</transition-list>
		</start-state>
	
		<!-- 
			============================================================
			===   Starts the FAQ application.                        ===
			============================================================ 
		-->

		<view-state id="faq.p_faq.vs_faq_list">
			<transition-list>
				
				<!-- Creates a new FAQ entry. -->
				<transition id="faq.p_faq.vs_faq_list.t_new"
				    target-state-ref="faq.p_faq.vs_edit_faq">
					<action-list>
						<new/>
					</action-list>
				</transition>
				
				<!-- Edits a new FAQ entry. -->
				<transition id="faq.p_faq.vs_faq_list.t_edit"
				    target-state-ref="faq.p_faq.vs_edit_faq"/>
				
			</transition-list>
		</view-state>
		
		
		<!-- 
			============================================================ 
			===   Edits a new or existing FAQ entry.                 ===
			============================================================ 
		-->

		<view-state id="faq.p_faq.vs_edit_faq"  state-ref="faq.p_faq.v_edit_faq">
			<transition-list>
				
				<!-- Stores an FAQ entry. -->
				<transition id="faq.p_faq.vs_edit_faq.t_save"
				    target-state-ref="faq.p_faq.bs_faq_list">
					<action-list>
						<store/>
					</action-list>
				</transition>
				
				<!-- Returns without saving. -->
				<transition id="faq.p_faq.vs_edit_faq.t_cancel"
				    target-state-ref="faq.p_faq.bs_faq_list"/>
				
			</transition-list>
		</view-state>
		
		<!-- 
			============================================================ 
			===   Returns to the FAQ overview.                       ===
			============================================================ 
		-->

		<back-state id="faq.p_faq.bs_faq_list"
		    back-to-view-model-in-domain-context-path-ref="faq.p_faq.vs_faq_list"/>
	
	</process-state-set>

</process>

Let us examine each submodel of this process step by step:

We need to implement two views, the FAQ list and the edit page. We do this quickly, implementing the overview first:

<?xml version="1.0" encoding="UTF-8"?>
<view id="faq.p_faq.v_faq_list" 
    title="FaqList"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.pik.as/schema/model/view-1.0.xsd">

    <part-set>
        <part>
            <content>
				
				<heading value="AvailableQuestionsAndAnswers"/>		
				
				<datagrid domain-type-ref="faq.d_faq" filter="opened">
					<datagrid-column-list>
						<property-column property-ref="faq.d_faq.question" filter-mode="contains"/>
						<button-column text="Edit" transition-ref="faq.p_faq.v_faq_list.t_edit"/>
					</datagrid-column-list>
				</datagrid>		
				
				<button transition-ref="faq.p_faq.v_faq_list.t_new" text="New"/>
				
            </content>
        </part>
    </part-set>
</view>

The view contains but one part and the single part contains a simple data grid. The data grid has two columns, one containing the question, the other a button activating the edit transition faq.p_faq.v_faq_list.t_edit mentioned when we created our process model. Additionally we add a new button below the grid.

Note how trivial the implementation of the search filter is. We define a filter mode for the single property column and specify it as contains. Additionally we tell the data grid to show the filter row at the top of the grid in an initially opened state. That's all.

We don't need to tell the system how or where to load the data, when and how to apply the filter, how to do paging or sorting. All that is pretty standard and therefor automatically provided by OpenSAGA.

Next we create the edit view under WEB-INF/resources/extensions/faq/models/processes/p_faq/views/v_edit_faq.xml. It's as trivial:

<?xml version="1.0" encoding="UTF-8"?>
<view id="faq.p_faq.v_edit_faq" 
    title="EditFaq"
    domain-type-ref="faq.d_faq"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.pik.as/schema/model/view-1.0.xsd">

    <part-set>
        <part>
            <content>
				<heading value="EditFaq"/>		
				
				<label value="Question" target-ref="question"/>
				<text-field id="question" property-ref="faq.d_faq.question"/>
				
				<label value="Answer" target-ref="answer"/><br/>
				<rich-text-field id="answer" property-ref="faq.d_faq.answer"/>

				<button text="Save" transition-ref="faq.p_faq.v_edit_faq.t_save"/>
				<button text="Cancel" transition-ref="faq.p_faq.v_edit_faq.t_cancel"/>

            </content>
        </part>
    </part-set>
</view>

It contains a heading (which will be translated automatically), two labels connected to two input fields (which e.g. causes mouse clicks on the label to activate the input field automatically) and the buttons for saving or canceling the view.

Now for the final step...

Before we can test our application one final model is required: We need to add the process model to the portal navigation. There are several ways to do this (we e.g. could create a navigation model from scratch) but for the sake of the example we opt for the most simple approach: OpenSAGA already contains an extension point for simple scenarios out of the box. You can overload the navigation model identified by base.n_applications. Overloading is explained in the section called “Model Overloading” and for our use case simply means that we create a new navigation model with an already existing ID. We create the following model:

<?xml version="1.0" encoding="UTF-8"?>
<navigation id="base.n_applications"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation=
        "http://www.pik.as/schema/model/navigation-1.0.xsd">

	<item-list>
		<item label="FAQ" description="FaqApplication"
		    process-start-state-ref="faq.p_faq.ss_start"/>
	</item-list>

</navigation>

The navigation model again is trivial - a single item list contains one navigation item and that item points to the process we defined in the section called “Implementing the Process” via the process model ID faq.p_faq.s_start.

That is it. Now you can restart the portal as explained in the section called “Setting Up the Project” and you should be able to access the working FAQ application. It is also provided on the OpenSAGA website as a sample download for you in order to check the complete application.

Describes the navigation of the portal. The navigation-reference-set describes a set of navigation-reference elements that each reference a navigation model (see the section called “The Navigation Model”). By defining a complete navigation set you are able to divide your view navigation areas into distinct navigation models, e.g. a left hand navigation, a support navigation, a link list for all pages and maybe some bottom navigation for the page footer. You are free in the number of distinct navigation models you define the only restriction being that the layout template being used for the actual view layout must be able to handle all navigation sets. If the template does not care for a specific navigation model, the navigation never will show up. If a navigation model expected by the layout template (due to a predefined navigation model ID) is undefined, an error might occur.

The process-reference-set element contains all processes that are used in the portal. For each process a process-reference element with the attribute process-ref has to be defined. This attribute refers to a process model. See the section called “The Process Model” for reference.

The domain type set contains all user defined domain types that are used in the portal. Each domain type has to be defined by an domain-type-reference element. The domain-type-ref attribute refers to a domain type model. See the section called “The Domain Type Model” for reference.

During enterprise development your development progress usually will be deployed in a staged manner, e.g. first you test your latest implementation on the development stage (or dev stage) in a closed circle of persons (e.g. just the development team), then you deploy your latest implementation artifacts to the quality assurance (or QA) stage for closer examination by a larger set of people (e.g. early adopters from the customer side or the quality management team) and then finally the latest changes are rolled out to production (or prod) stage.

OpenSAGA supports this layered rollout approach by defining staging models that hold particular settings for a given stage. The stages for a particular installation can be configured in various ways (see the section called “Configuring the deployment stage for the server” for more details).

The staging model describes all stage-dependent settings of your portal (see the section called “<stages />”). Usually each stage will include database connections and drivers, access settings and more (see the section called “<stage />”). Please note that stages are purely virtual - one physical stage (e.g. QA) can be made up of several logical stages (e.g. qa-server-1, qa-db, qa-eai and global). Each logical stage is represented by a staging model, the set of logical stages (when configured as explained in the previous paragraph) makes up the phyiscal stage definition.

Layout and skin models customize the appearance of a portal on an abstract level. Internally layout templates are used to implement a specific layout. These templates contain placeholders for layout-instance-specific data (e.g. the width of the left hand navigation or the logo to use). The layout and skin model connect the theoretical layout with specific layout settings in order to define a concrete layout.

The following process states can be used in a process model. Process states must be linked by transitions.

Back States

Returns to some parent state in the domain context path.

	Important
	Back states provide one of the most important navigational concepts in OpenSAGA. They allow transitions (which are always defined as having a start and an end state) to return to variable states by defining the semantic meaning interpretation of the back operation. the section called “<back-state />” contains explanations of the various modes supported by back states.

See the section called “<end-state />” for more details.

Transitions model state changes. Transitions always connect two states. Transitions additionally can contain action lists with an arbitrary number of actions that in turn allow to execute business logic when changing state.

The Domain Context Path

Internally OpenSAGA manages a data structure called the domain context path. The domain context path collects a list of tuples storing the views, which the user passed while working with the application, together with the associated domain object of the view.

Important

The domain context paths is automatically modified by OpenSAGA while the user steps through a process. Two simple rules are applied: If the transition connects to a back state the domain context path is shortened according to the rules defined by the specific back state. See the section called “Back States” for more details. In all other cases the next view (together with the associated domain object if any) is added to the domain context path. To repeat this: The domain context path grows all the time until the current process flow hits a back state. Back states are the only states that are able to shorten the domain context path. See also the section called “Domain Context” for more details about the domain context.

The relation model defines the relation between domain types. All relations are directed and include the usual cardinalities (0..*, 1..*, 0..1, 1..1). Relation models are described in more detail in the section called “<relation />”). All relation models are defined in one relation set model (see the section called “<relation-set />”). The relation set model is located at /resources/models/domain/relations.xml (do not change the filename!) and identified by the ID portal.domain.relations. Extensions must include a file of this name at the same location containing a relations set model with this ID in order to add new relations to the domain model.

Relations can be programmatically added to objects either by using the connect action (see the section called “<connect />”) or by using appropriate content element models, e.g. the single connect (see the section called “<single-connect />”) or multi connect (see the section called “<multi-connect />”) content element models.

Domain types represent all data known in a OpenSAGA installation. The following domain type model types are available:

Each domain type contains a number of property models, see the section called “Property Models”.

A domain type has a set of property sets. We differentiate properties in several types (dependent on the domain type model only a subset of these are available):

Each property has a property type that defines the type of data stored in the property, see the section called “Property Type Models”.

OpenSAGA supports a number of built-in property types and additionally provides an extension mechanism in order to be able to define extension-specific new property types. These two features are explained in the next two sections.

Translations are made up from a series of translation definitions (see the section called “Translation Definitions”). The available translations of a portal are defined by the merged set of all available definitions (in the order the stages are defined - it is possible to overwrite definitions).

The separation into translation definitions allows to collect tightly related definitions in one place. You can divide or collect your translations in any way that seems appropriate but we recommend using a logical structure.

All translation definitions are enumerated in the translations model (see the section called “<translations />”). The base translations for all portals are defined under the ID portal.domain.translations. Create a new model file under models/i18n/translations/translations.xml

A single set of translation definitions can be defined in a file under the path models/i18n/translations/definitions/some-name.xml. Each such file contains a translations definitions model (see the section called “<translation-definitions />”) and must be referenced from the set of translations (see the section called “Translations”). A set of definitions contains individual definitions that are resolved according to an algorithm defined in the section called “<translation-definition />”).

For all property types used in an OpenSAGA based portal it is possible to define individual formatters and converters in order to represent locale specific settings (see the section called “<type-converter-reference-set />” and the section called “<type-converter-reference />”). This can be done by defining your own property type models (see the section called “<property-type />”, for which the files are defined under /models/domain/property-types, definitions referenced in the property type reference set (see the section called “<property-type-reference-set />” and the section called “<property-type-reference />”) of the portal model (see the section called “<portal />”). Additionally you can overwrite existing definitions and thus provide new converters and formatters.

The session context exists for one user session, e.g. from login to logout.

The conversation context exists for the duration of one oncversation which means either a browser window lifecycle or a portlet instance lifecycle.

The process context exists for the execution of one specific process. As long as the user works in this process, all data in the process context is available. As soon as the process is switched or ends a new process context will be created.

The view context exists while the user is working with one view. It is special in so far as that it also contains all the data properties implicitly defined by input fields in the current view (property reading models in OpenSAGA lingo).

The request context is the most complex data context in OpenSAGA because it stores all information and data relevant for the current request. It is used throughout the framework in order to manage the request state.

The domain context is yet another special context that holds the data path navigated by the user (e.g. the data objects the user visited in order to get to the current state).

OpenSAGA provides a number of manipulative actions in order to create data. The following list gives a quick overview about the most important means: