Advanced Data Management: Action Definition

Modeling Actions with WebRatio Platform
605 views Published on Feb 24, 2015 | Time 20 min
Applies to: 7.2 or higher

In a Web application, you often need to manage the information shown to the user. Managing information means to create, update, or delete information. In this lesson we discuss an enhanced version of the Data Management pattern, which allows you to manage more than one piece of information at the same time. This is a common situation when you need to create the page allowing the user to create or update an invoice, an order or a purchase. In fact, usually these objects have a header and a detail section composed of several items. With WebRatio Platform you can easily model an Administration section in which the Web application user can manage the application data. In this lesson we describe the best practices for modeling an "Action Definition" containing the business logic needed in order to save the changes about a complex object such as an invoice.

Transcript

Table of contents

Advanced Data Management Overview

For the "Advanced Data Management" action definition example, let’s continue working on our "CRM" web project in which we already added the Domain Model composed of the "Purchase", "Purchased Items", "Product" and "Company" objects, and the "Administration" site view containing the "Purchase" area. This area contains the IFML model related to the Advanced Data Management. Let’s see how to model the "Action Definitions".

"Save Purchase" Action Definition

The "Save Purchase" action definition contains the operation chain that stores the information provided by the Web application user in the form and in the Multiple Form. In this case the Action Definition handles two Domain Model objects, the Purchase and the Purchased Item objects. The flow of the execution is the following: first, the Web application must check whether the user wants to create a new purchase or to update an existing one. Then the operation chain creates or updates the information. When the flow goes into the create branch, first it creates the "Purchase" information, which is the main one and then it creates all the "Purchased Items" pieces of information. On the other hand if the flow goes into the update branch, it deletes all the "Purchased Items" pieces of information related to that "Purchase", then updates the "Purchase" with new data and creates all the new "Purchased Items". This approach, when updating, is the simplest that you can imagine, you just delete all the "Purchased Items" related to a Purchase, you update the "Purchase" and then you re-create the new ones. Keep in mind that this is just an example that works as long as the "Purchased Items" are not linked to any other object, except for the "Product", with a Relationship. In fact, if you do have a relationship with another object you cannot delete and re-create the "Purchased Items", since you’ll lose all the foreign keys. Let’s now take a closer look at the Action Definition and let’s start from its "create" section.

The IFML Model

Let’s now take a closer look at the Action Definition and let’s start from its "create" section. The Action Definition starts with the Input Port that receives the required values from the IFML Model. The first operation executed is the "Is Not Null" operation that checks whether the Purchase exists or not. If the Purchase doesn’t exist a KO Flow is followed that leads directly to the Create Operation called "Create Purchase". Then after that the Purchase is created successfully another Create Operation is reached with an OK Flow. The second Create Operation inserts new Purchase Details and receives from the previous one the key of the new Purchase. This binding is done automatically by WebRatio Platform since the two entities are connected by only one relationship. This Create Operation must have the "Bulk" property enabled. The "Bulk" property allows sending and then writing more than one object at the very same time. In fact by default the Create Operation accepts only the first object received as input and ignores the other ones. With this property enabled, all the objects passed to the Create Operation are considered and the related insert statements are generated.
If the Create Operation is executed successfully then it leads to the OK Port. If the Purchase Exists an OK Flow is followed that leads directly to the Delete Operation called "Delete Purchase Details". This Delete Operation doesn’t have a Key Condition constraint that is replaced by a Relationship Role Condition based on the "PurchaseToPurchaseItem" relationship role. All the Purchase Details related to the existing Purchase are thus deleted. After the Delete Operation the next thing to do is to update the existing Purchase using an Update Operation. Once the Purchase is updated the next thing to do is to create all the new Purchase Details using a Create Operation on the "Purchase Detail" entity that receives data from the Input Port on a Data Flow. This Create Operation writes many objects at the same time so its "Bulk" property must be enabled.
An OK Flow starts from the Create Purchase Details and goes to the OK Port. All these operations must be surrounded with an Operation Group that creates a transaction, so that if one of them fails the entire execution is roll-backed. A KO Flow starts directly from the Operation Group and leads to the KO Port. Let’s also return a feedback error message from the KO Port in case the execution fails.

How to Model the "Save Purchase" Action Definition

From our "CRM" web project, select the "Save Purchase" action from the "Purchase" area in the "Administration" site view. Move to the Properties View and press the "Go to Action Definition" button, next to the "Action Definition" property. Now we can model the operation chain related to the Action Definition. To decide whether to create or update a purchase, let’s use an "Is Not Null" operation. To state that the "Is Not Null" operation is the first operation of the chain, let’s use an "OK Flow". Double-click on the OK Flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property, bind the "Input" parameter provided by the "Is Not Null" operation with the "Purchase Key" parameter provided by the Input Port. Press the "OK" button.

To create a new purchase, let’s use a "Create" operation.

To state that the "Create" operation must be executed after the "Is Not Null" operation when the purchase does not exist, let’s use a "KO Flow". To create the purchase items related to the purchase just created, let’s add another "Create" operation. Since we want the "Create Purchased Items" operation to store many "Purchase Item" object instances at the same time, check the "Bulk" property.

To state that the "Create Purchased Items" create operation must be executed after the "Create Purchase" create operation let’s use an "OK Flow". Now double-click on the OK Flow to make the binding. In the opening dialog you can notice that WebRatio Platform automatically binds the purchase primary key provided by the "Create Purchased Items" operation with the "purchase primary key" parameter provided by the "Create Purchase" operation. Press the "OK" button.

Let’s use two Data Flows to bind the information between the Input Port and the corresponding create operation. Select the "Data Flow" from the toolbar section related to "Flows" and click on the Input Port and then on the "Create Purchase" create operation. Double-click on the Flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "Purchase Object" parameter provided by the Create Operation with the "Purchase Object" provided by the Input Port. Press the "OK" button.

Now, select the "Data Flow" from the toolbar section related to "Flows" and click on the Input Port and then on the "Create Purchased Items" create operation. Double-click on the Flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "Purchased Item Object" parameter provided by the Create Operation with the "Purchase Purchased Items" provided by the Input Port. Then press the "OK" button.

When the execution of these operations is successful, the Action Definition must exit through the "Success" OK Port. Let’s use the "OK Flow" for this purpose. To update an existing purchase we need to:

  • Delete all the items related to the current purchase.
  • Update the current purchase instance with the new values.
  • Create the new "Purchased Items" related to the updated purchase.

This approach, when updating, is the simplest that you can imagine. Keep in mind that this is just an example that works as long as the "Purchased Items" are not linked to any other object, except for the "Product", with a Relationship. In fact, if you do have a relationship with another object you cannot delete and re-create the "Purchased Items", since you’ll lose all the foreign keys.

Let’s start adding the "Delete" Operation. When you add a new "Delete" operation, WebRatio Platform automatically creates a Key Condition. In this case we need a Relationship Role condition instead of the default Key Condition. Expand the "Delete Purchased Items" item, then right-click on the "Key Condition" item and select the "Delete" option. Now right-click on the "Delete Purchased Items" delete operation then select "Add" and then "Relationship Role Condition". Now press the "Select" button next to the "Role" property. In the opening dialog choose the "PurchaseToPurchasedItems [Purchase -> Purchased Items]" relationship and press the "OK" button to confirm.

To state that the "Delete" operation must be executed after the "Is Not Null" Operation when the purchase already exists, let’s use an "OK Flow". Double-click on the "OK Flow" to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property, then bind the "purchase primary key [oid]" provided by the "Delete Purchased Items" delete operation with the "Input Value" parameter provided by the "Is Not Null" operation. Press the "OK" button.

To update the existing purchase let’s use the "Update" operation.

To state that the Update Operation must be executed after the Delete Operation, let’s use an "OK Flow".

To bind the information between the Input Port and the Update Operation, let’s use a "Data Flow". Double-click on the Data Flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property, then bind the "Key Condition" parameter provided by the Update Operation with the "Purchase Key" parameter provided by the Input Port and the "Purchase Object" parameter provided by the Update Operation with the "Purchase Object" parameter provided by the Input Port. Press the "OK" button.

Now let’s add the Purchased Items related to the updated purchase. The "Create Purchased Items" create operation writes many objects at the same time so its "Bulk" property must be enabled.

To state that the "Create Purchased Items" must be executed after the Update Operation, let’s use the OK Flow. Double-click on the OK Flow to make the binding. Press the OK button to confirm the Default Binding.

To bind the information between the Input Port and the "Create Purchased Items" operation, let’s use a "Data Flow". Double-click on the Data Flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "Purchased Item Object" parameter provided by the "Create Purchased Items" operation with the "Purchased Item Objects" parameter provided by the Input Port. Then press the "OK" button.

When the execution of these operations is successful, the Action Definition must exit through the "Success" OK port. Let’s use the "OK Flow" for this purpose.

All these operations must be surrounded with an Operation Group since they must be executed in transaction. Select all the operation in the Action Definition Area, right-click on the selection and select "Refactor" and then "Surround with Operation Group". Since these Operations are surrounded with an Operation Group, we can use a single KO Flow outgoing from the "Save Purchase" Operation Group to the "Failure" KO port. Then double-click on the KO Flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and write an error message to bind to the "Error Message" parameter provided by the "Failure" KO port. Then press the "OK" button to confirm.

"Delete Purchase" Action Definition

The "Delete Purchase" action definition contains the operation chain that deletes a Purchase and all the related Purchased Items. This is the skeleton of the "Delete" action definition. The flow of the execution is the following: the Action receives the Purchase Key and passes it to a "Delete Operation" that with a "Cascade Delete Role" first deletes all the Purchased Items and then deletes the Purchase. Let’s now take a closer look at the Action Definition. The Action Definition starts with the Input Port that receives the Purchase Key from the "Purchase" List. The Purchase Key is passed to the "Delete Purchase" Delete Operation, based on the Entity "Purchase", as value for the KeyCondition. On the "Delete Operation" there is a "Cascade Delete Role"; this Cascade Role is based on the "PurchaseToPurchaseDetail" Relationship so that all the Details connected with the selected Purchase will be also deleted. Once the execution of the Delete Operation is completed an "OK Flow" that leads to the "Success" OK port handles the successful execution, while a "KO Flow" that goes to the "KO Port" handles the failed execution.

How to Model the "Delete Purchase" Action Definition

From our "CRM" web project, select the "Delete Purchase" action from the "Purchase" area in the "Administration" site view. Move to the Properties View and press the "Go to Action Definition" button, next to the "Action Definition" property.

Now we can model the operation chain related to the Action Definition. To delete a purchase, let’s use a "Delete" operation.

To state that the "Delete" Operation is the first operation of the chain, let’s use an "OK Flow". Double-click on the OK Flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and bind the "Key Condition" parameter provided by the "Delete" Operation with the "Purchase Key" parameter provided by the Input Port. Press the "OK" button.

For each instance of Purchase object we could have one or more instances of Purchased Item. So, when we delete an instance of Purchase, we need to delete all the corresponding instances of Purchased Item too.
Let’s use the "Cascade Delete Role" for this purpose. Right-click on the Delete Operation and select "Add" and then "Cascade Delete Role" option. Then press the "Select" button next to the "Rel. Role" property. In the opening dialog choose the "PurchaseToPurchasedItem" relationship and press the "OK" button to confirm.

When the execution of the Delete Operations is successful, the Action Definition must exit through the "Success" OK port. Let’s use the "OK Flow" for this purpose. Otherwise, if some error occurs during the execution of the Delete Operation, the Action Definition must exit through the "Failure" KO port. Let’s use the "KO Flow" for this purpose. Then double-click on the KO Flow to make the binding. In the opening dialog, uncheck the "Enable Default Binding" property and write an error message to bind to the "Error Message" parameter provided by the "Failure" KO port. Then press the "OK" button to confirm.