Control Flow Operations Overview
WebRatio Platform gives you three different operations for controlling the operation chain flow: "Is Not Null", "Switch", and "Loop". Let's see the purpose of each operation.
The "Loop" Operation
The "Loop" operation iterates over an array of objects. At each iteration, the operation provides both the current object and the current index as output parameters. The "Loop" operation must be the source of two distinct "OK Flows": one is followed for the next iteration; the other is followed to exit the "Loop". In addition to these two main sources, there is available another source code for the "OK Flow", which is not mandatory: the "Break" code. This "OK Flow" is used when the user want to break the loop at a particular operation, for example if a result of a business logic requires you to stop before the end of the loop. The "Loop" Operation can be used whenever you want to repeat the same business logic. Let’s consider our "CRM" Web application and suppose you want to send all users an email that reports on which is the best customer. The idea is to send this email once a week in order to announce the week’s best customer. You can learn how to schedule the execution of business logic by looking at the specific online lesson about that topic. This is the complete model of the "Action Definition" that would be used for sending this weekly email. This "Action Definition" works like this: first, we retrieve the full list of the Web application users using the "Selector" component. Then we loop on those users and, for each one, we retrieve the best company using another "Selector" component. Then we send an email to the user.
How to Model the "Send Best Customer Report" Action Definition
Let’s see now how to create the model shown previously. For this example let’s continue working on our "CRM" Web application. We already have a Domain Model defined, composed of the "Company" and "Best Customer" entities, a "Module Definition View" named "Action Definition" and an "Action Definition" named "Send Best-Customer Report". Double-click on the "Action Definition" to enter it. To retrieve the full list of users, let’s use the "Selector" component. Select the "Selector" component from the "Utility Component" section of the toolbar and click inside the "Action Definition". Double-click on the operation to change its name. Write a meaningful name, for example "All Users". Move to the Properties View and press the "Select" button next to the "Entity" property to choose the desired entity. In this case select the "User" entity and press the "OK" button to confirm. Now use an "OK Flow" to state that the "Users" component is the first to be executed in the "Action Definition". Select the "OK Flow" from the "Flows" section of the toolbar and click on the "Input Port" and then on the "Selector" component. To loop on the just-retrieved user list let’s use the "Loop" operation. Select the "Loop" Operation from the "Control Flow Operation" and click inside the "Action Definition". Double-click on the operation to change its name, for example "Iterate Over Users". To send the email you need to know the email address of the recipient but you also need to know the "Name" of the recipient if you want the email to be personalized. By default, the "Loop" operation accepts a single array as input to iterate over. You can add by hand one or more additional arrays to include the desired information. These additional arrays are referred to as secondary arrays. To add a secondary array, right-click on the "Loop" operation and select the "Add" and then "Secondary Array" option. Move to the Properties View to give a meaningful name to the array, in our case let’s use "recipients names". To provide the information needed to the "Loop" operation in order to iterate over the users, let’s use an "OK Flow". Select the "OK Flow" from the "Flows" section of the toolbar and click on the "Selector" Component and then on the "Loop" Operation. Double-click on the flow to make the parameter binding. Uncheck the "Enable Default Binding" option and bind the user "email" with the "Input Array" parameter, and the user "Full Name" with the "recipients names" parameter. Then press the "OK" button to confirm. To retrieve the Best Customer, let’s use a "Selector" component. Select the "Selector" component from the "Utility Component" section of the toolbar and click inside the "Action Definition". Double-click on the operation to change its name. Write a meaningful name, for example "Best Customer". Move to the Properties View and press the "Select" button next to the "Entity" property to choose the desired Entity. In this case, select the "Best Customer" entity and press the "OK" button to confirm. Since we want one instance of the "Best Customer" entity, let’s sort the results using the "money spent" information. Move to the Properties View and press the "Select" button next to the "Sort Attributes" property, select the "descending" option for the "money spent" attribute, and then press the "OK" button to confirm. In order to have just one instance, let’s write "1" in the "Max Result" property. To state that the "Best Customer" Selector Component is the first element to be executed inside the "Loop", let’s use an "OK Flow". Select the "OK Flow" from the "Flows" section of the toolbar and click on the "Loop" operation and then on the "Selector" component. Move to the Properties View and select "next" in the drop-down list next to the "Code" property. "next" means that this flow is executed for each iteration of the "Loop". To send an email to each user, we need to use a specific operation, the "Mail" operation. We will see how to configure it in a few minutes. For now, let’s see how to add it and connect it to the other operations of the "Action Definitions". Select the "Mail" operation from the "Utility Components" section and click inside the "Action Definition". Double-click on the operation to change its name, for example to "Send Mail". To state that the email must be sent at each iteration after the "Best Customer" selector component, let’s use an "OK Flow". Select the "OK Flow" from the "Flows" section of the toolbar and click on the "Selector" component and then on the "Mail" operation. After we send the email we have to proceed to the next iteration, as long as there are users to be processed. Let’s complete the iteration connecting the "Mail" operation with the "Loop" operation. We want to proceed when the mail is successfully sent, but also when there’s an error. Let’s use an "OK Flow" and a "KO Flow" for this purpose. Select the "OK Flow" from the "Flows" section of the toolbar and click on the "Mail" Operation and then on the "Loop" Operation. Then select the "KO Flow" from the “Flows” section of the toolbar and click on the "Mail" operation and then on the "Loop" Operation. To state that once the loop is completed the Web application must exit from the "Action Definition", let’s use an "OK Flow". In case there is no "OK Port" in the "Action Definition", you can add one by selecting the "OK Port" from the “Ports” section. Let's add the "OK Flow", select the "OK Flow" from the "Flows" section of the toolbar and click on the "Loop" Operation and then on the "OK Port". Move to the Properties View and select "end" in the drop-down list next to the "Code" property. "end" means that this flow is executed where there aren't any iteration of the "Loop".
The "Mail" Operation
The "Mail" operation is an operation that allows emails to be sent. In order for it to work you have to specify which "SMTP Server" will be used for sending emails. The "Input Parameters" of the operation include all the information related to an email: "Subject", "Content", "Recipients", and so on. The "SMTP Server" specifies the information used by the Web application to connect to the server for sending the emails. The main information required includes the "URL", the "Port", the "Username", and the "Password". To add an "SMTP Server" to your project, go to the Project View and, in the "Outline", right-click on the "Service/Data Providers" node and select "Add" and then "SMTP Server". In the opening dialog write all the necessary information and press the "Finish" button to confirm. Now you can go back to the "Action Definition" and select the "Mail" operation. Move to the "Properties View" and press the "Select" button next to the "SMTP Server" property. In the opening dialog, you can select the "SMTP Server" you just created and then press "OK". The content of the email can be specified using a template. The template is a file having the "xml.template" extension in which you can write the text of the email message by using some "Placeholder" where you want to insert dynamic information. Let’s see the template you can use for sending the "Best-Customer Report". The "Placeholders" are indicated through the "$$" symbol. In this example we have two different "Placeholders": the "recipient" and the "company". Once we reference the template from the "Mail" Operation, each "Placeholder" becomes an "Input Parameter" that can be bound to an incoming flow. To reference the template, select the "Mail" Operation, move to the Properties View and press the "Select" button next to the "Body Template File" property. In the opening dialog, select the template file you desire. In our example let’s select the "Best Customer Report" file. Press "OK" to confirm.
How to Configure the Mail Component
The "Mail" operation is an operation that allows emails to be sent. In order for it to work you have to specify which "SMTP Server" will be used for sending emails. The "Input Parameters" of the operation include all the information related to an email: "Subject", "Content", "Recipients", and so on. The "SMTP Server" specifies the information used by the Web Application to connect to the server for sending the emails. The main information required includes the "URL", the "Port", the "Username", and the "Password". To add an "SMTP Server" to your project, go to the "Project" View and, in the "Outline", right-click on the "Service/Data Providers" node and select "Add" and then "SMTP Server". In the opening dialog write all the necessary information and press the "Finish" button to confirm. Now you can go back to the "Action Definition" and select the "Mail" operation. Move to the "Properties View" and press the “Select” button next to the "SMTP Server" property. In the opening dialog, you can select the "SMTP Server" you just created and then press "OK". The content of the email can be specified using a template. The template is a file having the "xml.template" extension in which you can write the text of the email message by using some "Placeholder" where you want to insert dynamic information. Let’s see the template you can use for sending the "Best-Customer Report". The "Placeholders" are indicated through the "$$" symbol. In this example we have two different "Placeholders": the "recipient" and the "company". Once we reference the template from the "Mail" operation, each "Placeholder" becomes an "Input Parameter" that can be bound to an incoming flow. To reference the template, select the "Mail" Operation, move to the "Properties View" and press the "Select" button next to the "Body Template File" property. In the opening dialog, select the template file you desire. In our example let’s select the "Best Customer Report" file. Press "OK" to confirm. Press the "Next" button to proceed.
How to Complete the "Send Best Customer Report" Action Definition
Now that we also have the email message, let’s complete the model with the final binding. Double-click on the "OK Flow" connecting the "Best Customer" Selector Component and the "Mail" Operation. Uncheck the "Enable Default Binding" property and then bind the name of the company to the "company" Parameter. To pass the recipient name and email address to the "Mail" operation, let’s use a "Data Flow". Select the "Flow" from the "Flows" section of the toolbar and click on the "Loop" operation, and then on the "Mail" operation. Double-click on the flow and uncheck the "Enable Default Binding" property. Bind the "Next element" with the "to" parameter. The "Next element" represents, in this case, the recipient email. Then bind the "Next element (recipients names)" with the "recipient" Parameter. Press the "Next" button to proceed.
The "Switch" Operation
The "Switch" operation checks whether a parameter value is equal to one of the provided cases, and redirects the Navigation Flow in the direction associated with that case. The "Switch" Operation is very useful when you have different cases and, depending on the value assumed by the specific information, the Web application must execute different business logic. Let’s suppose we want to provide the user two buttons for saving the employee information: a "Save and Exit" button, which triggers the action execution and then redirects the navigation to the "Home Page", and a "Save and Continue" button, which triggers the action and takes the user back to the same page. Let’s see how to handle the button choice in the "Action Definition". In this example we do not show the operation chain needed for saving the employee information. For details, refer to the lesson about the "Data Management Action Definition". For this example, let’s continue working on our "CRM" Web application in which we already have the "Employee Management" Page in the "Sales Manager" Site View. Let’s select the "Save Employee" Action Definition and move to the Properties View. Press the "Go to Action Definition" button next to the "Action Definition" property in order to see the "Action Definition" section. Now let’s see how to handle the button choice. First, we need an "Input Parameter" representing the action selected by the user. Right-click on the "Input Port" and select the "Add" and then "Input Port Parameter". Then write a meaningful name for the parameter, such as "action". To evaluate the “action” parameter let’s use a "Switch" operation. Select the "Switch" operation from the "Control Flow Operation" section and click inside the "Action Definition". Double-click on the operation to change its name, for example to "Evaluate Action". Right-click on the operation in order to add the cases. Select the "Edit Case Values.." option. In the opening dialog, let’s specify the available cases. Press the "Add" button, then write the case value, for example "exit". To confirm, press the "OK" button. You can add several cases in the same way. In this particular example, we add another value, named "continue". Once you complete your configuration press the "OK" button. To state that the "Switch" operation is to be executed in the "Action Definition" after the data management, let’s use an "OK Flow". Select the "OK Flow" from the "Flows" section of the toolbar and click on the "Update" operation and then on the "Switch" operation. Then use another "OK Flow" to connect the "Create" operation and the "Switch" operation. To pass the value of the "action" parameter, let's use the "Data Flow". Select the "Flow" from the "Flows" section of the toolbar and click on the "Input Port" and then on the "Switch" operation. Double-click on the flow, uncheck the "Enable Default Binding" option, and bind the "action" parameter with the "Switch" parameter. Press the "OK" button to confirm. To have two different exit points from the "Action Definition" we need to create two different "OK Ports": one for the "Exit" case and another one for "Continue" case. To add an "OK Port", select the "OK Port" from the "Ports" section of the toolbar and click inside the "Action Definition". Give a name to the port, such as "Exit". Remember that you can create as many "OK" and "KO" Ports as you want. In this case we need another "OK Port" for the "Continue" case. To complete the model, let’s connect the "Switch" operation to each "OK Port" specifying when the Web application must reach one port or the other. Let’s use the "OK Flow" for this purpose. Select the "OK Flow" from the "Flows" section of the toolbar and click on the "Switch" operation and then on the "Exit" OK Port. Select the "OK Flow" and move to the Properties View. Select a "case" in the "Code" property to state when the "OK Flow" must be followed by the "Switch" operation. For example let’s select the "exit" case. This means that when the action parameter is equal to "exit", this "OK Flow" is executed. Then use another "OK Flow" to connect the "Switch" operation to the "Continue" OK port. You can avoid associating a code to this flow. This is the default flow, which means that when the input parameter value is not equal to any of the specified cases, the default flow is followed.
How to model the "Switch" Operation
The "Switch" operation checks whether a parameter value is equal to one of the provided cases, and redirects the navigation flow in the direction associated with that case. The "Switch" operation is very useful when you have different cases and, depending on the value assumed by the specific information, the Web application must execute different business logic. Let’s suppose we want to provide the user two buttons for saving the employee information: a "Save and Exit" button, which triggers the action execution and then redirects the navigation to the "Home Page", and a "Save and Continue" button, which triggers the Action and takes the user back to the same page. Let’s see how to handle the button choice in the "Action Definition". In this example we do not show the operation chain needed for saving the employee information. For details, refer to the onlie lesson about the "Data Management: Action Definition". For this example, let’s continue working on our "CRM" Web application in which we already have the "Employee Management" page in the "Sales Manager" site view. Let’s select the "Save Employee" action definition and move to the Properties View. Press the "Go to Action Definition" button next to the "Action Definition" property in order to see the "Action Definition" section. Now let’s see how to handle the button choice. First, we need an "Input Parameter" representing the action selected by the user. Right-click on the "Input Port" and select the "Add" and then "Input Port Parameter". Then write a meaningful name for the parameter, such as "action". To evaluate the "action" parameter let’s use a "Switch" operation. Select the "Switch" Operation from the "Control Flow Operation" section and click inside the "Action Definition". Double-click on the operation to change its name, for example to "Evaluate Action". Right-click on the operation in order to add the cases. Select the "Edit Case Values.." option. In the opening dialog, let’s specify the available cases. Press the "Add" button, then write the case value, for example "exit". To confirm, press the "OK" button. You can add several cases in the same way. In this particular example, we add another value, named "continue". Once you complete your configuration press the "OK" button. To state that the "Switch" operation is to be executed in the "Action Definition" after the data management, let’s use an "OK Flow". Select the "OK Flow" from the "Flows" section of the toolbar and click on the "Update" operation and then on the "Switch" operation. Then use another "OK Flow" to connect the "Create" operation and the "Switch" operation. To pass the value of the "action" parameter, let's use the "Data Flow". Select the "Flow" from the “Flows” section of the toolbar and click on the "Input Port" and then on the "Switch" operation. Double-click on the flow, uncheck the "Enable Default Binding" property, and bind the "action" parameter with the "Switch" parameter. Press the "OK" button to confirm. To have two different exit points from the "Action Definition" we need to create two different "OK Ports": one for the "Exit" case and another one for "Continue" case. To add an "OK Port", select the "OK Port" from the "Ports" section of the toolbar and click inside the "Action Definition". Give a name to the port, such as "Exit". Remember that you can create as many "OK" and "KO" Ports as you want. In this case we need another "OK Port" for the “Continue” case. To complete the model, let’s connect the "Switch" operation to each "OK Port" specifying when the Web application must reach one port or the other. Let’s use the "OK Flow" for this purpose. Select the "OK Flow" from the "Flows" section of the toolbar and click on the "Switch" operation and then on the "Exit" OK port. Select the "OK Flow" and move to the Properties View. Select a "case" in the "Code" property to state when the "OK Flow" must be followed by the "Switch" operation. For example let’s select the "exit" case. This means that when the action parameter is equal to "exit", this "OK Flow" is executed. Then use another "OK Flow" to connect the "Switch" Operation to the "Continue" OK port. You can avoid associating a code to this flow. This is the default flow, which means that when the input parameter value is not equal to any of the specified cases, the default flow is followed.
The "Is Not Null" Operation
The "Is Not Null" operation checks whether a parameter value is null and redirects the Navigation Flow in one direction or another. The "Is Not Null" operation is very useful when you have to model the business logic for managing the information of a Domain Model Object. For example, let’s suppose that in our "CRM" Web application we model a page in which the user can create or update the employee information. This is the flow chart representing the algorithm. As you may notice, at the beginning of the flow chart, a decision is made. If the employee exists, then the Web application saves the changes; otherwise it creates a new employee. To understand how to model the proposed example with the "Is Not Null" Operation, please refer to the online lesson about the "Data Management: Action Definition".