How to use the Connect Operation

Introduction

The Connect Operation is an operation used to enable the association between instances of two entities (the source entity and the target entity), connected by a specific relationship role.

The Connect Operation can manage single instances or sets of instances to connect:

1. One instance of the source entity to a set of instances of the target entity (and vice versa). For example, suppose you have the "Company" and the "Employee" entities connected with the 1 to N relationship role. You can use this operation to associate the employees with a company.
2. Sets of instances of target and source entities with the same cardinality (performing a pairwise connection). For example, suppose you have the "Employee" and the "Departments" entities connected with the N to N relationship role. You can use this operation to associate a set of employees with a set of departments.

Source and target entity connections are chosen applying conditional expressions.

Properties

• Id. The unique key automatically assigned by WebRatio Platform to identify the operation (e.g., "cnu1").
• Name. A meaningful name for the operation, used as label (e.g., "Connect Employee to Departments").
• Relationship Role. The Domain Model Relationship Role on which the operation is based (e.g., "EmployeeToDepartment").

Configuration

The connect operation can be configured through a context menu that can be reached with a right-click on the operation either in the work area or in the Outline View.

The context menu contains the following options:

• Add > Flow. Adds an outgoing data flow to the operation, which can be used to transport information to other elements.
• Add > OK Flow. Adds an outgoing OK flow to the operation. The OK flow is activated when the operation performs correctly, it can be used to transport information and it will cause the execution of its target element.
• Add > KO Flow. Adds an outgoing KO flow to the operation. The KO flow is activated when the operation is not able to perform correctly, it can be used to transport information, and it will cause the execution of its target element.
• Add > Property. Adds a custom property to the operation. A property is composed of name and value and permits to mark the element for different purposes.
• Add > Source Key Condition. Adds a key condition to the source entity of the selected relationship role. This condition restricts the set of the available source entity instances through the primary key.
• Add > Source Attributes Conditions. Adds an attributes condition to the source entity of the selected relationship role. This condition restricts the set of the available source entity instances.
• Add > Source Relationship Condition. Adds a relationship role condition to the source entity of the selected relationship role. This condition restricts the set of the available source entity instances.
• Add > Target Key Condition. Adds a key condition to the target entity of the selected relationship role. This condition restricts the set of the available target entity instances.
• Add > Target Attributes Condition. Adds an attributes condition to the target entity of the selected relationship role. This condition restricts the set of the available target entity instances.
• Add > Target Relationship Role Condition. Adds a relationship role condition to the target entity of the selected relationship role. This condition restricts the set of the available target entity instances.

Input and Output

The Input and the Output of the operation are accessible through the Parameters Binding dialog of incoming and outgoing flows, respectively.

Input

You can access to the input parameters, by opening the Parameters Binding dialog by double-clicking or by selecting the Binding property on an incoming flow to the connect operation. Here you can find the conditions of the target and source entities of the selected relationship role named with suffix [Target] and [Source].

The input of the connect operation consists of all conditions defined on the target and source entities of the relationship role on which the operation is defined.

In this example, the available conditions are related to the N to N relationship role modeled between the "Employee" and the "Department" entities.

Output

You can access the Output Parameters, by opening the Parameters Binding dialog by double-clicking or by selecting the Binding property of an outgoing flow from the connect operation.

Here all Output Parameters can be bound with the Input Parameters of the target element.

The output of the connect operation consists of the key attributes of the entities connected by the relationship role on which the connect operation is defined. The entity to which the key attributes refers is specified in brackets.

In this example, the available key attributes refer to the "Employee" and the "Department" entities.

Example

The purpose of this section is to show the usage of the connect operation through examples. Suppose you have two entities in the Domain Model: "Employee" and "Department", and they are connected with an N to N relationship role.

Suppose you want to give the user the chance to select an employee and connect some departments to him/her. The resulting IFML model is shown in the following figure.

The "Connect Employee to Departments" action definition is modeled in this way:

Model the action definition as shown in the previous image and let's take a detailed look at the steps necessary for configuring the "Connect Employee to Departments" connect operation:

1. Select the Connect Operation.
2. Move to its Properties View to define the Data Binding connection.
3. Change the Name property (e.g., "Connect Employee to Departments").
4. Set the relationship role on which the connect operation is based, pressing on the Select button next to the Relationship Role property, choosing the "EmployeeToDepartments" relationship role from the opened dialog and then press the OK button.

   

5. Define the input parameters. Double-click on the input OK flow to open the "Parameters Binding" dialog. Uncheck the Enable Default Binding property and bind the key attributes to the related key conditions. Then press the OK button.

   

6. Define the output parameters. Double-click on the output OK flow to open the "Parameters Binding" dialog. Uncheck the Enable Default Binding property and bind the "Source oid [Employee]" parameter. Then press the OK button.

   

Now that the definition is complete, let's open the "Home" site view and complete the IFML model.

1. Define the Parameters Binding of the "Connect" navigation flow. Double-click on the navigation flow to open the "Parameters Binding" dialog. Uncheck the Enable Default Binding property and bind the "oid" attribute of the simple list with the "Department Oid" input parameter of the action. Then press the OK button.

   

2. Define the Parameters Binding of the outgoing data flow of the "Employee Details" component. Double-click on the data flow to open the "Parameters Binding" dialog. Uncheck the Enable Default Binding property and bind the "oid" attribute of the details component with the "Employee Oid" input parameter of the action. Then press the OK button.

   

3. Define the Parameters Binding of the outgoing OK flow of the action. Double-click on the OK flow to open the "Parameters Binding" dialog. Uncheck the Enable Default Binding property and bind the "Employee Oid" output parameter of the action with the key condition of the details component. Then press the OK button.

   

4. Define the Parameters Binding of the outgoing KO flow of the action. Double-click on the KO flow to open the "Parameters Binding" dialog. Uncheck the Enable Default Binding property and write a string an error message string, for example "Error during the association". Then press the OK button.

   

Now you can generate the Web application to see the result, and it will be as shown in the following image:

Additionally, you can add to this management the Disconnect Operation, which allows the user to disconnect the employee from the departments, obtaining the following model:

Refer to the "How to use the Disconnect Operation" article to learn how you can integrate your model with this operation.

How to use the sample project

You can use the "ConnectSample.zip" file attached to this article, to test the usage of the Connect Operation.

Follow these steps to use the project:

1. Import the sample project into the WebRatio Platform. You can learn how to do this by watching the "Organize the Workspace" online lesson.
2. Generate the project with the "Generate and Run on Cloud" command if you have a WebRatio Community Platform version; otherwise, use the "Generate and Run" command.
3. Visit http://localhost:8080/ConnectSample/page2.do or http://freeXXXXX-freeapp.eu.webratio.net/page2.do with any browser, click on the "Connect Departments to Employee" menu to test the first example or click on "Connect and Disconnect Departments to Employee" to test the second example.