versata business logic designer concepts...

Versata Business Logic Designer Concepts Guide

Versata Business Logic Designer for WebSphere Studio

VERSATA, INC.300 LAKESIDE DRIVESUITE 1500OAKLAND, CA 94612-3534PHONE: 510.238.4100INTERNET: HTTP://WWW.VERSATA.COMVBLD-C-01

NoticeThis offering is based on technology from the Eclipse Projecthttp://www.eclipse.org

CopyrightCopyright © 2000-2003 Versata, Inc. All rights reserved. Printed in the United States of America.This software and documentation package contains proprietary information of Versata, Inc. and is provided under a license agreement containing restrictions on use and disclosure. The software and documentation is also protected under copyright law. Reverse engineering of the software is prohibited.The information in this document is subject to change without notice. Versata, Inc. provides this publication "as is" without warranty of any kind, either express or implied, including but not limited to the implied warranties or conditions of merchantability or fitness for a particular purpose. Versata Business Logic Designer and Versata Logic Server are trademarks of Versata, Inc.IBM, the Ready for WebSphere Studio Software Emblem, and the term Ready for WebSphere Studio Software are trademarks of IBM and are used under license from IBM. IBM does not warrant and is not responsible for the operation of this software. The developer of this software has performed all testing, including all testing required by the Ready for WebSphere Studio Software offering. For more information about the IBM Ready for WebSphere Studio Software offering, visit www.ibm.com/partnerworld/developer/websphere/ready.htmlIBM and DB2 are registered trademarks and AIX, WebSphere, and WebSphere Studio Application Developer are trademarks of IBM Corporation.Microsoft, Microsoft SQL Server, Microsoft Internet Explorer, Windows, Windows NT, and Microsoft Access are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Oracle and SQL*Plus are registered trademarks and SQL*Net is a trademark of Oracle Corporation.Java, JavaBeans, JavaScript, JDBC, JDK, JNDI, and Solaris are trademarks and Sun MicroSystems is a registered trademark of Sun MicroSystems, Inc.Adaptive Server Enterprise, jConnect, and Sybase SQL Server are trademarks of Sybase, Inc. in the United States and/or other countries.Informix Dynamic Server and Informix-Driver for JDBC are trademarks and Informix is a registered trademark of Informix Corporation.Adobe, the Adobe logo, Acrobat, and the Acrobat logo are trademarks of Adobe Systems Incorporated.All company, product, service, and trade names referenced may be service marks, trademarks, or registered trademarks of their respective owners.

Table of Contents

CHAPTER 1 Business Logic Automation Using Rules................................................... 5Design and Runtime Environment..................................................................................................................6

Design Time - a feature plug-in to WebSphere Studio............................................................................6Runtime - services installed in WebSphere Application Server..............................................................7

Versata Foundation Classes (VFC) - client access ...........................................................................7Persistence Management ..................................................................................................................7VLS Console.....................................................................................................................................7JSP Adapter - tags for retrieval / update...........................................................................................7

What are Declarative Business Rules?............................................................................................................8Business Rules Functionality Compared to Spreadsheet Functionality ..................................................9Example Object Model ............................................................................................................................9Parent/Child Associations......................................................................................................................10Example of a Rule..................................................................................................................................10Characteristics of Rules .........................................................................................................................11Rules and Business Logic Bean Domains .............................................................................................12

CHAPTER 2 Classification of Declarative Business Rules........................................... 15Derivation Rules ...........................................................................................................................................16

Example .................................................................................................................................................16Multiple data object updates through cascading rules ...........................................................................19

Child to parent cascade...................................................................................................................19Parent to child cascade ...................................................................................................................20

iii

Validation Rules............................................................................................................................................ 21Referential Integrity Rules............................................................................................................................ 23

Example ................................................................................................................................................. 23Constraint Rules............................................................................................................................................ 25

Example ................................................................................................................................................. 25Action Rules ................................................................................................................................................. 27

Example ................................................................................................................................................. 27

CHAPTER 3 Transaction Logic Processing ...................................................................29Logic Processing Steps ................................................................................................................................. 30

Pre-processing Events............................................................................................................................ 30Generated Logic Execution ................................................................................................................... 30Post-processing Events .......................................................................................................................... 30

Transaction Management.............................................................................................................................. 31Transaction Cache ................................................................................................................................. 31Commit-time processing - logic on transaction boundaries .................................................................. 31JTS Integration ...................................................................................................................................... 32

Persistence Management............................................................................................................................... 33Order of transaction logic processing ........................................................................................................... 34

Nest levels.............................................................................................................................................. 35Modification of state flags..................................................................................................................... 35

CHAPTER 4 Accessing Transaction Logic.....................................................................37Connecting to the VLS ................................................................................................................................. 38

Security and VLS ........................................................................................................................... 38Reading data from BLBs .............................................................................................................................. 39

Querying for BLB Data ......................................................................................................................... 39Pre-processing events for Reads..................................................................................................... 39

Writing to BLBs............................................................................................................................................ 40VLS processing for BLB writes ............................................................................................................ 40Transaction Boundaries ......................................................................................................................... 40

Query Beans - Views on TLBs ..................................................................................................................... 41

CHAPTER 5 Business Uses of Rules ...............................................................................43What the Versata Logic Server Is Not .......................................................................................................... 46

iv

CHAPTER 1 Business Logic Automation Using Rules

The Versata Business Logic Designer comprises a business logic automation engine and design studio that captures business logic rules and executes them as J2EE components running within WebSphere. It is designed to accelerate the construction and maintenance of transaction processing systems, simplify WebSphere application development, and promote Enterprise-class scalability.Because Versata rules are easier to understand, write, change and debug than the hand-coded programs they replace, software systems can be built faster and with more consistent quality and performance. In addition, the time and quality benefits should increase over the entire software life cycle, since new requirements can usually be handled by simple rule changes and additions. These changes are applied consistently during re-automation by Versata and typically do not introduce new bugs or errors --- the downfall of most software maintenance efforts.

5

BUSINESS LOGIC AUTOMATION USING RULESDESIGN AND RUNTIME ENVIRONMENT

Design and Runtime EnvironmentThe Versata Business Logic Designer includes both a design environment and a runtime environment.

Design Time - a feature plug-in to WebSphere StudioThe Business Logic Designer is delivered as a feature plug-in for WebSphere Studio, and integrates with the J2EE design and deployment facilities supplied with the development platform. Within the design environment rules can be defined for Business Logic Beans (such as Account, Holding, Quote, etc) and implementation artifacts can be created and deployed. Business Logic Bean metadata is stored as XML files within the WebSphere Studio workspace and can be revision controlled for multi-user development environments.

Figure 1 Versata Business Logic Designer and Versata Logic Server components within the WebSphere Studio environment

6

BUSINESS LOGIC AUTOMATION USING RULESDESIGN AND RUNTIME ENVIRONMENT

Runtime - services installed in WebSphere Application ServerThe Versata Logic Server is a runtime transaction rules engine that executes business logic within a J2EE environment. A development copy of the Versata Logic Server is provided with the Versata Business Logic Designer for testing. It deploys into, and integrates with, the WebSphere Application Server - Express test environment. Components of the runtime environment include:

Versata Foundation Classes (VFC) - client accessThe Versata Foundation Classes (VFC) are a set of libraries that allow client applications to connect to the Versata Logic Server and access Business Logic Beans. VLSContext is a session bean that provides a context for client application interactions with the Versata Logic Server. As illustrated in the diagram, these libraries can be used to write client applications such as JSP tag libraries, java applications and EJB session beans.

Persistence ManagementBusiness Logic Beans operate strictly at the logic layer. When they need to make physical read/write requests, these are delegated to separate eXtensible Data Access (XDA) Classes. XDA classes are pre-supplied by Versata for SQL, or you can provide your own for non-SQL data (eg. CICS).

VLS ConsoleThe VLS Console enables you to monitor logic execution, and specify a number of administrative parameters including role authorizations, database server connection parameters, and transaction managers

JSP Adapter - tags for retrieval / updateVersata provides JSP support, where you can use WebSphere Studio’s JSP editing tools to build JSP applications that utilize a set of predefined Versata JSP tags.

7

BUSINESS LOGIC AUTOMATION USING RULESWHAT ARE DECLARATIVE BUSINESS RULES?

What are Declarative Business Rules?Declarative business rules are simple, unambiguous statements that define derivation, validation, constraint, action and referential integrity enforcement. When creating solutions with the Versata Business Logic Designer you design in terms of what the application needs to do, not how it does it.

Business rules define what data values should or should not be, based on calculations or restrictions. You do not need to write code to arrive at these data values; the Versata Business Logic Designer generates this code based on your rule definitions.You define business rules for the objects in your data model, using graphical tools and simple language in the Business Logic Designer. Rules are properties of data, and fire only when data changes state. Business rules are stored in the repository, along with the data model.The Business Logic Designer allows you to extend and customize declarative rules in a variety of ways. It allows you to define action rules that call system-supplied or user-defined Java methods. You also can reference methods in rule expressions and augment the generated code with your own code. Your edits can range from event-handling code, to subclassing the Versata Logic Server Classes that provide the building blocks for rules and other business object code.

Business Rules Functionality Compared to Spreadsheet Functionality

One way to understand business rules is to compare their functionality to that of spreadsheets. The following table provides this analogy.

Rules defined in the Versata Business Logic Designer are high level, unordered assertions about data used to formulate and direct the transactions within a J2EE application server.:

Spreadsheet functionality Declarative business rules functionality

Unordered - Spreadsheet cell formulas can reference other computed cells. It is the job of the spreadsheet to determine a proper order of cell evaluation.

Business Logic derivations can refer to other derived attributes, including ‘multi-object’ logic such as the Holdings currentValue. The VLS determines a correct order of evaluation, and when to access related data. This determination is automatically repeated when derivations are altered, thus automating a significant element of maintenance.

8


Example Object ModelIn order to discuss rules and their various characteristics, it is helpful to give examples in terms of a known object model. The following examples use the Trade Tutorial object model to illustrate the basic rule types. Refer to the Trade Tutorial for examples of how to write rules against this object model with the Versata Business Logic Designer.

Reused - when you state that a cell is the sum of a column, the cell is recalculated when any one of a variety of changes is made to the dependent data, eg. a value in the colunm is altered, or a row is added or deleted in the column.

All transactions that affect referencing data trigger the referencing logic to run. For example, in the sample database, Holdings are adjusted when Transactions are added, deleted or altered. This eliminates an entire class of design errors, assures data consistency, and reduces implementation effort.

Optimized - spreadsheets ‘prune’ the tree of calculations, when changes are made, to maintain fast response.

Logic is optimized to bypass access to related data when the referenced values are not altered. Such optimizations are repeated on each logic change, helping to assure performance remains strong even over maintenance cycles.

Spreadsheet functionality Declarative business rules functionality

9


Parent/Child AssociationsIn the following sections, one-to-many (1:n) relationships between objects are referred to as parent/child associations. In this scenario, a single ‘parent’ can be associated with many ‘children’. Attributes contained in parent and child objects are referred to as ‘parent attributes’ and ‘child attributes’. Because the default data mapping layer (XDA) provided with the Versata Logic Server maps objects to RDBMS database tables in a 1-to-1 fashion, persistent instances of these objects are sometimes referred to as ‘parent record’ and ‘child record’.

Example of a RuleHaving said that Versata rules are assertions about data, here is an example of an assertion:

Figure 2 The Trade Object Model

10


For an object Account,

the value of the attribute portfolioValue

is

the sum of currentValue for each Holding associated with the Account

The transactional effect of this assertion is that, when the currentValue of any of the Holdings, associated with the Account, changes, the portfolioValue is adjusted up or down as needed.

Characteristics of RulesHere are some important points to notice about the rule:

It implements logic for multiple objects. From what we have seen, the rule affects at least two entities -- Account and Holding. In fact, the rule also involves two other objects - Transaction and Quote, since the currentValue attribute is derived from information in both of these entities. Refer to the tutorial for more information on rules to calculate the currentValue.

Figure 3 The portfolioValue rule as defined in the Versata Business Logic Designer

11


It is declarative. This means that the designer did not specify how the system is to get this result. The developer did not need to decide whether the "sum" function resides on the Holding object, or the Account object. He did not need to implement arrays of Holdings, counters, or cross-object get and set methods.It is transaction independent. There are several transactions that affect the currentValue of a holding. A buy transaction will increase the currentValue: A sell transaction will decrease it. In addition, new transactions may be added in the future (to convert options to stock, for instance.) These all may affect the currentValue of a Holding. The important thing is that the rule to re-calculate the portfolioValue will be applied automatically, to any transaction that requires it. No developer analysis is needed to determine when to apply the rule.It is unordered. Although a specific sequence of operations will be implemented (Holding will be updated before Account), the developer need not worry about the ordering of operations. A rules compiler in the Versata Logic Server will unravel the dependency between objects and sequence operations correctly.It will be automatically optimized for runtime. Performance is frequently a concern when utilizing EJB remote interfaces and container managed persistence. The Versata Logic Server provides services within the WebSphere Application Server to overcome many of these concerns. For instance, the Versata Logic Server maintains a transaction cache for cross-entity interactions inside of WebSphere. This means that the appropriate Transaction, Holding and Account objects will be brought into the Logic Server cache in a single read from the database. The entire rule chain will execute from this cache, speeding execution while guaranteeing data integrity. In addition, all the interactions between Transactions, Holdings, and Accounts will be done with simple Java method calls, rather than with expensive EJB access.

Rules and Business Logic Bean DomainsFrom the example above, we can make these additional observations about Versata rules. The first observation is that rules apply to data, specifically they apply to data when it changes. From this we can see that, in applications where persistent data does not change, this type of rule will not be very useful.Note: This characteristic is one of the main differences between "inference rule engines" and

"transactional rule engines". Inference engines collect their data and make decisions independent of transactions. The result of the decision may or may not be used in a transaction. With most inference engines, the transaction will be designed and coded by the developer using traditional coding methods. Transactional rules engines, on the other hand, drive transaction logic. Automated transactions proceed (or don't proceed) because of rules. These automated transactions may be customized with hand-coded logic, but the bulk of the calculations, validations and evaluations come directly from the executing rule.

12


The second thing we observe about Versata logic rules is that they govern the interactions of a set of business objects (and their attributes) in a J2EE application. Here we will coin a new phrase - this set can be thought of as a domain of Business Logic Beans (BLBs), where the domain is a collection of entity-type BLBs that will be needed to carry out a series of common business functions. Business Logic Beans include Transaction Logic Beans and Query Beans. Transaction Logic Beans are the aggregation of objects, their attributes and associated rules. Query Beans represent an attribute based view on to a set of Transaction Logic Beans.The specification of a domain usually begins with an object model (or a database schema.). This jump-starts the definition of the domain. The remainder of the domain specification is done through rules.Note: For those familiar with software engineering domain analysis, a repository of Versata

business objects and rules capture both the commonalities and variabilities of a set of applications to be deployed in the enterprise.

The complete specification for all of the domain objects and their interactions is stored as "metadata". This metadata is kept in an XML-formatted repository and is available, at design time, to the Versata Business Logic Designer and other applications accessing objects in the domain.What remains then is to classify the types of rules that can control the behavior of a domain of BLBs.

13


14

CHAPTER 2 Classification of Declarative Business Rules

The Versata Business Logic Designer allows you to define the following types of business rules:

Derivation rulesValidation rulesReferential integrity rulesConstraintsActions

The business rules that may be applied to an element in a data model depend on the element’s object type, as shown in the following table.

Type of business rule Applicable data element

Derivation, Validation Attribute

Constraints, Actions Transaction Logic Bean

Referential Integrity Associations

15

CLASSIFICATION OF DECLARATIVE BUSINESS RULESDERIVATION RULES

Derivation RulesDerivation rules define how an attribute’s value is computed when a database update occurs. Derivations can be aggregations of child record values (sums or counts), replicates of parent attributes, or formulas based on values of other attributes in the same object. You can create derived attributes that are used for calculation of other attributes’ values but are not stored in the database. These attributes are called virtual attributes. A virtual attribute is calculated as needed rather than being physically stored in the data source. Whenever an attribute has a derivation rule, the Versata Business Logic Designer by default generates a validation rule to prevent user updates. This validation rule can be changed, if necessary.Each derivation rule can cause other derivation rules to fire. This cascading of rules enables complex update processing across multiple data objects. For an example of this process, see “Multiple data object updates through cascading rules” on page 19.

ExampleDerivations are computational, which means that the value of that attribute is arrive at by a formula. An example is a rule that says, for a Holding, the‘qtyOnHand = qtyBought - qtySold’In addition, computational derivations can specify sophisticated qualifications and can navigate to other objects to use their values in computations. An example of this is a rule that says, for a Transaction,‘The price used to calculate the amount of the Transaction is the price of the associated Quote object ’From the Business Logic Designer, the rule looks like this:

16


The following are types of derivation rules.

Figure 1 The derivation rule for the ‘price’ attribute of the Transaction object

Rule type Explanation

Sum A sum rule derives a parent attribute value by adding values of a specified attribute in the associated child objects. A sum rule can optionally include a qualification expression that restricts child records included in the sum.

The generated component code for a sum rule:

• Initializes the parent sum attribute value to be 0 on insert of parent record.

• By default, raises an error when a user tries to insert or update the parent sum attribute directly. (This default can be overridden by changing the Prevent User Updates validation rule.)

• Adjusts the sum attribute value by subtracting values of deleted child objects, adding values of inserted child objects, and subtracting or adding the changes to values of updated objects. (Note that most processing occurs in the child object). Defining sums as described here results in superior performance because it does not result in aggregate queries every time the summed value needs to be changed.

17


Count A count rule derives a parent attribute value by counting the number of records in a specified child object. A count rule can optionally include a qualification expression that restricts the child records included in the count.

The generated component code for a count rule:

• Initializes the parent count attribute value to 0 on insert.

• By default, raises an error when a user tries to insert or update the parent count attribute directly. The default can be overridden by changing the Prevent User Updates validation rule.

• Adjusts the count attribute value: decreases the value by one for each deleted child object and each updated child object that no longer meets the specified condition, and increases the value by one for each inserted child object and each updated child object that newly meets the specified condition. (Note that most processing occurs in the child object). Defining counts as described here results in superior performance because it does not result in aggregate queries every time the counted value needs to be changed.

Parent Replicate A parent replicate rule derives a child attribute value by copying a value from an attribute in a related parent object. A replicate occurs when a new child object is created or when a new parent is assigned to an existing child.

Additionally, a Maintained option is available to specify whether updates to the replicated attribute in the parent should be cascaded to related children. By default, replicates are not maintained.

Replicates are useful in reducing joins, and in making parent data values available for use in other business rules.

The generated component code for a parent replicate rule:

• Copies the parent attribute value to the child replicate attribute on insert.

• Copies the new parent attribute value to the child replicate attribute if a foreign key is changed in the child.

• Changes the child replicate attribute value to NULL if a foreign key is nullified.

• Cascades updates from the parent attribute to child replicate attributes, if the replicate is maintained. (Note that most processing occurs in the parent object).

• By default, raises an error when a user tries to insert or update the child replicate attribute directly. The default can be overridden by changing the Prevent User Updates validation rule.


18


Note: Derivation rules other than defaults are not supported on primary or foreign keys.

Multiple data object updates through cascading rulesA derivation rule fires when a user action changes the value of an attribute used in the rule. The firing of one rule often results in changes to other attributes, causing the firing of rules that use those attributes’ values. Because of this cascading of rules, one user action can result in updates to multiple data objects, including changes that start in a parent and cascade to its children. The cascading can begin with a number of user actions, including a change in the value of a primary key, the deletion of a parent object, and the deletion of a child object.

Child to parent cascadeA change to the value of a child object that is used to provide a sum, used as a qualification condition in a validation rule, or used as a foreign key, can cause an adjustment to a parent object. The change in the parent object may trigger other rules in turn. For example, in the Trade object model, when a Transaction is created with a transType of 1 (ie. a ‘buy’ transaction is created), many other attribute values change.

Holding.qtyBought is adjusted, because its derivation rule sums the ‘buy’ TransactionsHolding.qtyOnHand is adjusted, because its derivation rule uses Holding.qtyBoughtHolding.currentValue is adjusted, because its derivation rule uses Holding.qtyOnHandAccount.portfolioValue is adjusted, because its derivation rule sums the currentValue attributes of all it’s associated Holdings

Formula A formula rule derives an attribute value by evaluating an expression on other attribute values from the same object. Formula rules can reference data modification operations (Inserting, Updating, Deleting), include system-supplied or developer-defined methods that return a value, and include if-then-else conditional structures.

The generated code for a formula rule calculates the attribute value on insert or update.

Default A default rule specifies the value of an attribute when a user does not enter a value on insert. This specification can be a literal number value, a quoted string, or a method that returns a value. Subsequent user updates can change a default value.

The generated code for a default rule:

• On insert, checks if an attribute is NULL.

• If an attribute is NULL, inserts the default attribute value.


19


Parent to child cascadeA change to a parent record that is used in a maintained replicate rule may cause an update to child records to receive the new value. For example, if Transaction.price and Transaction.commission were both maintained replicates of Quote.price and Account.commRate, respectively, when either Quote.price or Account.commRate changed Transaction.amount would be recalculated (since it is derived from these two values).Note that, in the Trade Tutorial, Transaction.price and Transaction.commission are not maintained since intention is to use the stock price and commission rate at the time the Transaction was created, and not allow retrospective modification to these attributes.Parent-to-child cascades also may result from referential integrity updates.

20

CLASSIFICATION OF DECLARATIVE BUSINESS RULESVALIDATION RULES

Validation RulesValidation rules define limitations for attribute values based on developer-defined conditions. The Versata Business Logic Designer also allows you to restrict attributes’ updatability and nullability through validation rules. The following are types of validation rules.

Validation rule type Explanation

Valid Values A validation rule limits attribute values to the values in a selected attribute in another object, which serves as a value table.The generated code for a validation rule validates attribute data against these values.

A value table is a transaction logic bean containing lookup values that can be used to validate user entries. Almost any set of finite and relatively permanent data is appropriate for a value table. For example, U.S. state abbreviations, credit limit categories, and payment methods are typical uses of value tables.

You can use a transaction logic bean both as a regular transaction logic bean and as a value table. Attributes in a transaction logic bean may be used as a value table without interfering with the attributes' primary use in the transaction logic bean. In this case, the Versata Business Logic Designer generates code that checks attributes to maintain referential integrity as well as code that checks the attributes to validate against the value table data.

Nullability The Business Logic Designer provides a Value Required validation rule with a system-supplied error message. You can specify in this rule that an attribute value cannot be NULL.

The generated code for a Value Required rule defines the attribute as not NULL, and nullability is checked in the client during update processing.

Updatability The Business Logic Designer provides a Prevent User Updates validation rule with a system-supplied error message. You can specify in this rule that an attribute value cannot be updated by users.

The Versata Business Logic Designer automatically applies a Prevent User Updates validation rule to derived attributes. You can override this default, even for non-persistent, derived attributes.

The generated code for a Prevent User Updates validation rule raises an error when a user tries to update the attribute directly. (A user can enter an attribute value for a newly created object. If the attribute is derived, the newly entered value is overridden by the derivation when the object is saved.).

21

CLASSIFICATION OF DECLARATIVE BUSINESS RULESVALIDATION RULES

Data type The Business Logic Designer allows you to change data types for attributes via scalar fields. For Text, Number, and DateTime types, you also indicate a sub type. In the case of Text attributes, you also can change the size.

The Business Logic Designer checks data type changes, prohibiting changes between mismatched types, changes to indexed attributes and key attributes, and changes to AutoNumber when data already exists in an attribute. Data type checking is performed on both the client and the server.

Validation rule type Explanation

22

CLASSIFICATION OF DECLARATIVE BUSINESS RULESREFERENTIAL INTEGRITY RULES

Referential Integrity RulesReferential integrity rules preserve relationships between objects when data manipulation language (DML) updates occur. For each association in your object model, you can indicate whether you want to enforce referential integrity.You can define separate rules for parent updates, parent deletes, and child inserts/updates. The Versata System supports standard referential integrity rules with additional provisions for Cascade Update, Cascade Delete, and Cascade Nullify. The generated code for a default referential integrity rule rolls back the entire user update request if a referential integrity violation occurs. The rollback reverses all changes to objects that were caused by the update request. By default, the VLS enforces referential integrity.

ExampleAssociations typically imply a parent-child association between entities. Through the use of intermediate entities, they can also be used for more complex relationships. An example of a parent-child association in the Trade application is a rule that says,‘An Account Has Holdings’As we will see, the Versata Logic Server automates almost all operations between related entities. For instance, an Account can automatically count and "sum" all of its Holdings. Holdings can automatically check for sufficient funds in the related Account.Furthermore, as they are entered, Holdings can automatically check to ensure they are associated with valid Accounts. These are only some object behaviors enabled by relationships.The following table lists the types of referential integrity rules available in the Versata Business Logic Designer.


Restrict There are three Restrict rules:

1) Prevent parent update if children are present.

2) Prevent parent delete if children are present.

3) Prevent child insert/update if parent is not present.

Each of these rules can be defined separately. You may edit the rules and the system-supplied error messages.

Cascade Update A cascade update rule, or Update Children on Parent Update, indicates that foreign key values for child records should be updated to match an updated parent key value.

23

CLASSIFICATION OF DECLARATIVE BUSINESS RULESREFERENTIAL INTEGRITY RULES

Cascade Delete A cascade delete rule, or Delete Children on Parent Delete, indicates that related child records should be deleted when a parent is deleted.

Cascade Nullify A cascade nullify rule, or Null Children Foreign Key on Parent Delete, indicates that foreign key fields for related child records should be nullified when a parent key is deleted.

Cascade Insert A cascade insert rule, or Insert Parent If None on Child Insert/Update, indicates that if an inserted or updated child record has no parent record, a record should be inserted into the parent data object with a primary key that matches the child foreign key. Note that this option is available only if the parent object does not have required fields other than the primary key fields.


24

CLASSIFICATION OF DECLARATIVE BUSINESS RULESCONSTRAINT RULES

Constraint RulesConstraints are object-level rules you can use to enforce value changes to attributes. Constraints consist of a condition (such as whether the quantity of stock in a Transaction meets a minimum threshold), an action (either to accept or reject the pending change), and an error message. When the condition evaluates to true, the action is taken, and a specified error message is returned. The condition is evaluated whenever any attribute specified in the condition is going to change.Constraints can:

Reference data modification operations (Inserting, Updating, Deleting).Use the :Old function to reference attribute values prior to update.Include system-supplied and developer-defined methods. Govern derived attributes.

All attributes, derived or otherwise, in the conditional expression of a constraint must be located in the same Transaction Logic Bean.You may define multiple constraints on an object. All constraints are evaluated when an update to a object occurs. The generated code for a constraint rolls back the entire user update request if a constraint violation occurs during the update. The rollback reverses all changes to objects that were caused by the update request. A transaction is rolled back when the conditional expression for a Reject When constraint evaluates to true.You can enter a customized message to display when the constraint prevents a user transaction from committing.Note: Constraints are inherently unordered. We do not recommend that you attempt to reorder

them.

ExampleConstraints define legal states in the system. For transactional systems they define legal values of data that are allowed to exist. A rule to restrict margin selling in the Trade application is one such state. It says, on Account‘Balance can’t be less than zero’This simple-sounding constraint rule will be automatically included in any rule chain that can potentially affect the Account balance. For instance, here's a ‘Buy’ rule chain which will be constrained by the rule above.

When buying a stock the following happens:

1. A Transaction object is inserted by the client application

25

CLASSIFICATION OF DECLARATIVE BUSINESS RULESCONSTRAINT RULES

2. The logic processing in the Transaction object finds the stock's price from the associated Quote

3. Next, it calculates the amount of the Transaction based on the quantity, the price of the Quote and the commission rate from the Account

4. Then it begins to debit the Account balance with the Transaction amount in the associated Account object

5. Finally, it encounters the constraint in the Account object, and if the constraint is violated (if the new balance will be less than zero), it unwinds the entire operation (rolls back changes to the Transaction and Account objects).

This example reinforces three important characteristics about rules.First, notice that we did not have to write a "Buy" method to perform this chain of events. A simple change [insertion] to a Transaction object began the process. The Logic Server understood all of the objects involved. It understood all of the rules and all of the cross-logic between the object attributes. It understood all of the dependencies, including which was the "inner-most" and "outer-most" object. It understood how to optimize the chain of events, including caching the Account, Transaction and Quote objects during the transaction because their attributes were needed several times. Finally, it understood where to put transaction boundaries and how to deploy the transaction into the WebSphere application server.Next, notice that the rule is not tied to any particular transaction. Instead, it applies to the "state" of the system. The rule would apply also if the user tried to withdraw money from his account - he would be prevented from withdrawing more funds than he had. The Versata Logic Server is responsible for maintaining the declared state and identifying all the possible transactions that affect that state.Finally notice that the declaration of rules was completely unordered. We actually created this rule to constrain margin selling before we even knew how the balance would be derived.This is "what" not "how" that Chris Date talks about when categorizing declarative logic rules.There is another type of constraint rules --- a transition constraint.Transition constraints define legal transitions, or changes from one state to another. An example is a rule that says that for a Holding,‘Old qtySold cannot be more than New qtySold’ (In other words, in the Trade application, it is not possible to "un-sell" a stock)During rules processing, the Versata Logic Server maintains old and new values of all attributes. This allows rules to easily check and constrain transitions between object states.

26

CLASSIFICATION OF DECLARATIVE BUSINESS RULESACTION RULES

Action RulesAction rules, more completely called Event/Condition/Action (ECA) rules, extend the transaction logic processing capability of the Versata System by incorporating your procedural code into the declarative model. The Event is the operation and entity being watched by the Logic Server. The Condition must be met in order to proceed. The Action is the side-effect that should result from a condition being metActions enable you to customize the Versata Business Logic Designer-generated business objects through calls to developer-defined methods. Values of the Transaction Logic Bean can be passed as method parameters and customizations are preserved automatically when business rule components are regenerated.

ExampleAn example of an action rule is one that says,‘When adding a new Transaction, if the transType is "sell", credit the related Account balance’.The Versata Logic Server will take an action when all other rules leading up this event/condition have evaluated "true".

27

CLASSIFICATION OF DECLARATIVE BUSINESS RULESACTION RULES

28

CHAPTER 3 Transaction Logic Processing

After you declare business rules for each Transaction Logic Bean, you build and compile the rules logic as Java classes. In the Versata Business Logic Designer you define derivations and constraints at the object level, not for specific transactions. The system then automatically generates transaction-specific logic when you build and compile business rules into the Java classes. These classes execute on the VLS and IBM WebSphere Application Server. The VLS provides logic execution services and acts as a container for the business objects created by the Business Logic Designer, while IBM WebSphere Application Server provides application execution services. Versata System centralizes the transaction logic execution on the VLS, hence each client application that accesses the same TLBs automatically inherits transaction logic. When you redeploy business rules, the Versata Business Logic Designer automatically analyzes all data dependencies, rebuilding to achieve a correct and optimal processing order. This rebuilding protects against a gradual loss of coding efficiency due to multiple patches.Most of the processing logic for rules resides in the business object files, in Java code. The object files have pluggable data access modules, with separate files called Versata Connectors that perform data access. The Versata System includes default Connectors for SQL-based data sources, like RDBMSs. You must obtain specialized Connectors separately or write your own Connectors to provide data access to non-SQL data sources.

29

TRANSACTION LOGIC PROCESSINGLOGIC PROCESSING STEPS

Logic Processing StepsTransaction logic for any TLB is executed by calling the save() method on the generated Java class that implements that TLB. All types of modifications (insert, update, or delete) are processed via this single method to ensure consistency and reusability of the generated as well as user-supplied logic. The following sections describe the major steps of logic processing.

Pre-processing EventsUser specified optional event handlers are invoked before generated logic processing is executed. They are typically used for initializing certain values, logging/auditing for debugging purposes or performing custom validations before rules-based processing can begin. Each type of modification (insert, update, and delete) is supported for these events.

Generated Logic ExecutionSeveral different steps are performed for different types of rules during this phase. See the table below for various rule types that are processed in this phase and the order of processing for these types. Note that at the end of this phase, one or more related objects may have been read and/or updated based on multi-object rules (e.g. sums, counts, association constraints, etc.) that may have been defined on the TLB on which the original save() method was called. All of these objects at this stage are maintained in a transaction cache for further processing and persistence. Transaction cache is discussed further in the transaction management section.

Post-processing EventsUser specified optional event handlers are invoked after the logic processing step is completed also. The typical use of post-processing events is to perform custom validations on computed data. However, user code can also modify the object in such an event handler. In such a case special care must be taken to ensure logic processing is invoked again from this event for data integrity purposes, while taking care of avoiding infinite loop of processing. More information on these loops is provided in a following section. Each type of modification (insert, update and delete) is supported for these events.

30

TRANSACTION LOGIC PROCESSINGTRANSACTION MANAGEMENT

Transaction ManagementTransactions are managed by implicit or explicit boundaries as determined by the application requirement. For example, a single TLB save() method invocation will start a new transaction if there is no transaction already active in the context in which this save() method is invoked. These behavior implements implicit transactions. On the other hand, if a transaction is already in progress (started either by the client application, or by another TLB), the TLB in question will (can) join such a transaction. This behavior implements explicit transactions.

Transaction CacheAs discussed in the generated logic execution section, one or more related objects may get accessed (read and write) during logic processing of each object. Further, a client initiated transaction can invoke logic processing for multiple objects in a single transaction. In either case, multiple objects are accessed (some objects more than one time) in a single transaction. VLS ensures transaction consistency automatically by using a transaction cache. Transaction cache provides significant benefit in the following areas,1. Write Cache - All objects that are modified during a transaction get persisted to their

datasource only at the end of the transaction (see the section on commit-time processing below). This ensures better performance for complex transactions where the same object may be modified multiple times.

2. Read Cache - All queries that will read the TLB data (whether issued by automated business logic or your Java code) are cache-aware, meaning that they check if the requested data is in the cache before issuing SQL statements to the datasource. This ensures consistency by providing latest copy of data in that transaction and improves the performance by reading the same data only once per transaction.

Commit-time processing - logic on transaction boundariesSpecial commit time customization in the form of events is enabled for logic that requires a transaction be seen as a whole. For example, a validation that ensures that a HOLDING has 1 or more TRANSACTIONs must be performed only after all objects under question have been submitted in that transaction.

31

TRANSACTION LOGIC PROCESSINGTRANSACTION MANAGEMENT

JTS IntegrationVLS transactions are fully integrated with JTS support for WebSphere. If a client application thread is already in a JTS transaction and a TLB is invoked from it, VLS will join the JTS transaction, perform its function and return control back to the client application. Commit-time processing and transaction cache behavior described above is transparent, whether a JTS transaction is active or not.

32

TRANSACTION LOGIC PROCESSINGPERSISTENCE MANAGEMENT

Persistence ManagementData access to the TLBs is implemented by persistence management provided by the VLS. XDA (Extensible Data Access) architecture implements this behavior completely independent of the generated Java logic, ensuring generated logic be truly independent from the type of datasource used. At runtime, specific connector to a given datasource is attached to a given TLB for data access for that TLB. Pre-supplied RDBMS connectors as part of VLS provide data access for DB2, Oracle and Sybase. However, using XDA architecture custom connectors can be implemented fairly easily to provide data access from environments such as legacy systems and ERP applications.Significant performance-oriented functionality is provided in this layer of VLS. Please refer to the Performance Tuning Guide for details on configuration and tuning options to maximize performance using VLS-based persistence management.

33

TRANSACTION LOGIC PROCESSINGORDER OF TRANSACTION LOGIC PROCESSING

Order of transaction logic processingTo use rules effectively, you should understand the order in which they are executed. As in a spreadsheet, the processing order is implicit, and cannot be modified directly by you, although you can nest rules to model complex behavior among multiple objects. For some information about nesting, see “Nest levels” on page 35.The Versata Logic Server processes business rules in a defined order. When a modification (insert, update, or delete) is made to a Transaction Logic Bean and then saved, a set of operations are carried out in within the bean itself. The following table summarizes these operations in the order in which they occur..

Each type of modification (insert, update, or delete) enforces the set of rules indicated by an ‘x’. For each modification, all local calculations and validations are done first. These are followed by modifications to related objects in the form of cascades to child objects and adjustments to parent objects. Each of these related modifications then implements the dependency graph in its entirety as well. Please review “Order of rule processing operations” on page 11 in the Reference section of the Versata Business Logic Designer help for details on each type of processing.

Operation Scope Insert Update Delete

Before Insert/Update/Delete Event local x x x

Set Defaults local x

Attribute Alterability Check local x

Parent Check / Fetch Parent Replicate local x x

Evaluate Formula local x x

Attribute Validation Check local x x x

Business Object Constraint Check local x x x

Nullability Check local x x

Conditional Action local x x x

Child Cascades child x x x

Parent Adjustment parent x x x

After Insert/Update/Delete Event local x x x

34


Nest levelsWhen changes are propagated across multiple Transaction Logic Beans, the scope of execution is nested. Within each nest level, rules are re-executed in the same order of operations as specified in the table above. The same TLB instance can be reentered multiple times across nesting levels. After all of the nest levels are completed, the transaction logic returns to its starting point at the first nest level. After each nest level is completed, the transaction logic ‘unwinds’ like function calls being popped off of a stack, until the transaction is completed back at nest level 1.

Modification of state flagsLogic code in a Transaction Logic Bean can determine whether an insert, update, or delete is taking place on it by using the following methods: isInserted(), isUpdated(), and isDeleted(). It is possible for isInserted() and isUpdated() to return different Boolean (Yes/No) values depending upon the current nest level. The operation on the component differs depending upon the context. For example, if a row is being inserted, and transaction logic execution has entered a related object (thus incrementing the nest level), and then the logic re-enters the original object (incrementing the nest level again), isInserted() would return True in the first nest level and isUpdated() would return False. However, upon re-entry in the third nest level, isInserted() would return False and isUpdated() would return True. There is also a method available called isChanged() to determine whether or not an attribute has changed. This method returns True if this attribute has changed either by the client application of as a result of computation within logic processing.

35


36

CHAPTER 4 Accessing Transaction Logic

BLBs get accessed from client applications primarily by using VFC (Versata Foundation Classes) library. The following services are provided by VFC to facilitate access to BLBs hosted by the VLS. Note that client applications can be of various kind and configurations, ranging from a JSP-based web application to an XML-based SOAP agent, to a session EJB.

37

ACCESSING TRANSACTION LOGICCONNECTING TO THE VLS

Connecting to the VLSVLS provides an interface that enables access to the BLBs hosted in it. This interface is deployed as a Session EJB (VLSContext) within WebSphere environment. This bean can be accessed directly by using J2EE APIs, or it can be accessed via client APIs supplied in the VFC (VSSession). This client-side wrapper to the VLSContext simplifies the programming model for JNDI lookups and it provides certain value added client-side services such as error handling, meta data caching, etc.

Security and VLSAccess to the VLSContext (and hence VLS) can be secured as per WebSphere security model on SessionBeans. VFC APIs however, still require authentication parameters to maintain a user-specific context for that particular application instance. This is largely useful for highly interactive UI-oriented applications where user identities do not need to re-established for every interaction. However, using custom security management in VLS, this need of authentication can be completely relegated to WebSphere if needed.

38

ACCESSING TRANSACTION LOGICREADING DATA FROM BLBS

Reading data from BLBsOne of the key performance requirements for multi-tier systems is to use a coarse-grained approach for reading and writing data. That is, to minimize the number of trips to the server.For example, instantiating objects in the server (for example, an EntityBean) and making per-attribute calls to get/set values would be fine-grained access, and perform very poorly. On the other hand, moving just the data values of objects to the client layer for read / write would reduce the number of calls to the server and server overhead, and would perform much faster. Further, when a list of objects are needed to be used in the client (such is the case in most UI applications), then an optimized list-based access needs to be provided that behaves much like DBMS cursors.This corresponds to the J2EE pattern of Value Lists (result lists) of Value Objects (row objects sent to the client). In VFC, value list pattern is implemented by VSResultSet and value object pattern is implemented by VSRow in VFC.

Querying for BLB DataClient applications query for BLB data by preparing a VSQuery of selection criteria for that BLB, which is executed to obtain a VSesultSet of VSRow objects that match the criteria. Result Sets enable you to retrieve results by scrolling (first, last, previous or next) to obtain rows, which provide access to VSData objects that represent attribute values.BLBs are not typically instantiated in the VLS during retrieval process unless non-persistent attribute values are requested by the client application. Significant performance-oriented behavior is provided all through the above process. Please refer to the performance tuning guide in the reference section for details.

Pre-processing events for ReadsYou can provide custom event handlers (beforeResultSetFill event) for a BLB to manipulate the data that is being sent to the client. Typically custom security or custom computations for client UI are performed in such an event.

39

ACCESSING TRANSACTION LOGICWRITING TO BLBS

Writing to BLBsEvery data value that is represented by a VSData instance can be updated by various set methods (based on datatypes) available on that object. Each modification to this instance is maintained in the VFC layer without any communication to the VLS. As a result, each VSResultSet (that contains multiple VSRows, that contain multiple VSData items) maintains which VSRows are modified in it. A single invocation (updateDataSource()) on the VSResultSet object is provided to ensure all changed VSRows (recall each VSRow represents a distinct BLB object) are sent to the VLS in a single call to the server.

VLS processing for BLB writesWhen a request is received by the VLS for BLB updates (via the updateDataSource() method on VSResultSet) with one or more row instances, each VSRow instance is turned into a BLB instance and save() is invoked on it to perform the logic as discussed in earlier chapter.

Transaction BoundariesAll of the updated rows from a single ResultSet are processed in a single transaction and server interaction (as discussed in “Transaction Management” on page 31). If updates from multiple ResultSets need to be bundled into a single transaction, VFC supports APIs to begin and commit transactions explicitly. The events described in “Commit-time processing - logic on transaction boundaries” on page 31 occur when this commit is received.For example, you might need to send a new HOLDING and a set of TRANSACTIONS to the server as a single transaction. Notice that the Trade JSP application automatically manages these boundaries based on the datasource dependencies defined using JSP tags (try to create this specific example of HOLDING and TRANSACTIONs using that application).

40

ACCESSING TRANSACTION LOGICQUERY BEANS - VIEWS ON TLBS

Query Beans - Views on TLBsOne of the key aspect of client-server/relational environment is the availability of Views in addition to the base Tables. There are tremendous performance benefits of performing joins in the database. In addition, the application programming model stays transparent in terms of which type of object is being accessed (views vs. base tables, both from read and write perspective). This improves maintainability of the application as new data elements can be introduced, performance can be tuned, etc. without having to make a lot of changes in the application code. QueryBeans provide such extensive functionality as Relational Views on top of TLBs in multi-tier environments. Following are three functional aspects of QueryBeans.1. Joins - Like RDBMS views, Query Beans enable you combine related data into a single

virtual value list (of value objects) on which you can issue dynamic queries. This significantly improves performance as such a request is translated into a SQL join and executed at the datasource instead of in the application.

2. Projections - like RDBMS views, Query Beans enable you to select which attributes to retrieve. This can be used for security purposes (e.g. assign less security to Query Bean than to it’s corresponding base TLB), and performance (you can reduce network traffic by projecting only needed data).

3. Updates - updates can be issued directly against VSRows representing QueryBeans. VLS decomposes such an update into corresponding base TLB instances and exactly the same logic is applied whether the update is issued via a QueryBean or directly against the base TLB.

41

ACCESSING TRANSACTION LOGICQUERY BEANS - VIEWS ON TLBS

42

CHAPTER 5 Business Uses of Rules

It is also helpful to classify the business use of rules. Although there are many more, here are six business uses of transactional rules.1. Rules can automate data validation. Data and transactions are more accurate. Validation

coding is eliminated.A fundamental use of rules in the Versata Business Logic Designer is for data validation. Validation rules are a type of constraint.Although validation is frequently overlooked when estimating the amount of business logic in an application, it's design and development consumes costly programming resources. Moreover, validation (and related error handling) code is usually sprinkled throughout various client-tier and logic-tier components. This makes logic difficult to re-use and maintain.Using rules to specify attribute validations has several benefits. First, validations, like all rules, will be applied consistently across all applications. This increases system integrity.In addition, validation metadata, like other rule-based metadata, can be accessed through object methods. This makes it possible for a client components to derive their behavior from business entity metadata. This extends the use of the "Model" in the Model-View-Controller architecture and could allow client components to adapt automatically to changes in business logic.

2. Rules can preserve the association between related objects when they change. System consistency is assured. Coding to check and maintain relationships is eliminated.

43

BUSINESS USES OF RULES

Referential integrity refers to the need to maintain consistency between one business object and all of the other objects that refer to it. For example, in the Trade application, where there is a relationship between an Account and its Holdings, it would not be good business policy to allow an Account to be deleted if it had active Holdings. Similarly, the business undoubtedly has a policy ensuring that Holdings are created only if the user has a valid Account.In applications where all data is kept in the same relational database, enforcing referential integrity can be left to the database management system. If, however, there is the potential for data to come from more than one source, integrity must be assured through application code. In J2EE applications, the place for this code is in EJBs (Whether it should be placed in the parent entity EJB or the child entity EJB, or in a third, session EBJ is frequently debated.)Versata business logic rules provide an easy and consistent way to enforce relationships and integrity, even between objects in different databases or legacy applications.Versata rules can enforce very sophisticated integrity. For instance, to perform automatic clean-up, a rule could be define that, when deleting an Account, the user's Profile should be deleted as well.Enforcing referential integrity in Transaction Logic Beans greatly increases integrity of data entered. Automating this behavior with rules improves the functionality of systems without tedious hand-coding.

3. Rules can automatically synchronize related attributes in different objects. Complex transactions are always implemented correctly. Performance is optimized.One of the most common patterns coded into EJB logic is getting and setting the attributes in related objects within the scope of transactions. The IBM-version of the Trade application "Buy" function is a simple example. Given a UserID, stock Symbol and Quantity, the Buy operation:

Finds the related stock from the Quote entity (the developer first defines a find method to do this)Checks that the Quote is valid and gets its priceFind the related account for that UserID (the developer first defines a find method to do this)Checks that the account is valid and gets its balanceCreates a holding and checks to see that this succeedsDebits the account balance (the developer first defines a debit method to do this)

(The Trade code notes that the logic to check that there are sufficient funds to buy the holding has not been implemented.)

44

BUSINESS USES OF RULES

Rules can be used to automate this transaction. The relationship rule between the Holding and Quote entity allow us to automatically get the price of a stock. The relationship between the Transaction and Account allow us to automatically get and update the Account balance. And as we saw earlier, logic to check for sufficient funds can also be implemented with a simple constraint.One of the most effective uses of rules is to automatically implement complex, cross-entity transaction logic. Rules assure that the logic is implemented correctly, and that it can be enhance with simple rule modifications.

4. Rules can enforce operational policies and respond to change when policies change. Logic is defined in well-understood declarations. Policies are enforced uniformly.Often, organizations begin to look at rule-based systems when they need comply with government or industry regulations, especially when those regulations change. Constraint rules are useful for this purpose.

5. Rules can identify interesting data. Flagged data can be used for personalization or cross-marketing.Although transactional rules are not primarily used for personalization or data mining, such rules do "watch" transactions as they flow through the J2EE application server. For example, with a rule on the Account entity, a sales representative can be automatically notified when a new user, with an account balance greater than $100K, is added to his territory. Or a user may set a flag on his holdings, to notify him when a stock drops more than 25%Since rules watch for changing data, any behavior initiated by a change in state can be a candidate for a rule.

6. Rules can initiate asynchronous events. Events integrate the rule-based system with external applications. Events initiate exception processing.Although Trade is an entirely synchronous application (transactions are committed or rolled back immediately), most enterprise systems have some asynchronous operations.For example, when a user updates his account information, a rule could create an XML formatted message and place it on a message queue to be picked up by the corporate CRM system. Or the system could start a workflow process, and advise an investment representative to contact this customer who had just deposited $100K in his account.Rules watch data changes and can initiate synchronous transactions or asynchronous events based on those changes.

45

BUSINESS USES OF RULESWHAT THE VERSATA LOGIC SERVER IS NOT

What the Versata Logic Server Is NotThis chapter concludes with a discussion of what transactional rules are not. This may help to clarify when and when not to use transactional rules for WebSphere applications.As we discussed, the Versata Logic Server is not an inference rules engine. Typically inference (or decision support) engines sit outside of the transactional system. They may be used to build expert systems or produce input to transactional components, but they do not directly implement the transactions contained in components such as EJBs.The Versata Logic Studio is also not a Case tool. Case tools produce models and code "stubs" which are then implemented and integrated. Versata rules are executable and they need no further development.The Versata Logic Suite is not a "4GL". Fourth-generation languages shortcut procedural programming but they are not declarative. A 4GL function will generally map, one-to-one, to a coded procedure. They do not unravel dependencies, sequence complex chains of operations and map to logic across many entities.Finally, although the Versata Business Logic Designer does construct Java components, it is much more than a code generator. It uses high level specifications to create and directly execute applications. In each case, a specification (the "what") is input to the Versata Business Logic Designer and is stored as exchangeable XML. From the specification, the system automatically parses, analyzes and creates the desired applications utilizing highly performing enterprise Java frameworks (the "how".)The Versata approach is particularly well-suited to WebSphere applications with substantial business logic, where application requirements are evolving or where project time, costs or EJB development skills may be an issue.

46

versata business logic designer concepts...

Documents