Developing a business process in 2E
Overview
The following is an introduction to an approach to developing a business process for Websydian Express using 2E.
There are many possible variations of how you can do this, but the following description should take you through the most common steps in a sequence that should ensure that you do not suddenly need information that you do not have available at the time.
- Identify pages and page content
- Identify events and input for events
- Create functions in 2E
- Create Templates using the Page Modeler
- Code PageGenerators
- Code ProcessEntryPoint function
- Code EventHandler functions
- Generate and build
- Deploy objects
- Define in Administration interface
- Test
1. Identify pages and page content
The first two steps mostly consists of getting an overview of the business process. It is especially important to consider how the user must interact with the application.
The first step is to find out which web pages you want to show to the user - and determine the data you want to show on each page.
For each page you must determine:
- Which data should be shown as output fields in the detail region? (These fields more or less corresponds to output fields in the CTL format of a 2E display file).
- Whether you need a grid? If you do, which output fields you need to show in the grid? (These fields more or corresponds to output fields in the RCD format of a 2E display file).
Basically, you can only define one grid for a page. If you need to have more than one grid on a page, you must define the additional grids as include pages.
You must determine which page you want to show as the first one, when the business process is activated from the menu.
After considering the output fields and which page you want to show first, you must consider how you want to navigate between the pages - this leads to the next step.
2. Identify events and input for events
Identifying events
Each event provides a possibility for a user to interact with the application. The normal way events are implemented are as buttons or links on the pages.
This means that if a user must be able to go from one page to another, the first page has to contain an event, which activates a function calling the new page.
Events are not required to lead to a new page, in many cases the event just reloads the page it belongs to.
As an example:
- A page contains a list of records in a grid. At the press of a button, the list is repositioned based on a text entered in an input field.
So for each page, you must consider which interactions the user needs to be able to make with the application - as a rule of thumb, each interaction will lead to an event.
If you have a grid on the page, you should consider whether the event is related to the grid (e.g. an update record button on a grid line) or the detail region (e.g. an insert/create new record button).
For each event, you must also find out which page to show after the event has been handled. All EventHandlers has to call a PageGenerator.
Please note that an event can be used on more than one page. For example, a "Home" event could be shown on all of your pages (all of them would bring the user back to the first page shown - and all of the event should be handled by the same EventHandler).
After identifying the events and the pages the events will call, it is normally a good idea to check whether all pages either will be called from an event or is the first page shown when the business process is started.
If any pages are not called, they will never be shown - and it is a clear indication that one or more events are missing.
Identifying input fields for events
In many cases, the program handling the event will need some input. The most common input is fields that must be entered by the user.
For each event you must consider which information the user must be able to deliver to the program handling the event.
As examples:
- An event for creating a record in the database (e.g. a create user button on a create user page) - will often need all of the fields from the record as input fields
- An event used for positioning a grid on a web page - will normally have the first field of the key used to order the list as input
- An event showing the next page in a list - will normally not have any input fields
Identifying parameterfields for events
In addition to the fields entered by the user, there will in some situations be a need to transfer some information from the PageGenerator function to the EventHandler program. As the PageGenerator never actually calls the EventHandler, this information can't be transferred as normal parameters.
By using the SetParm/SetGridParm/GetParm/ValidateParm APIs, you can transfer data from a PageGenerator to an EventHandler in a secure manner.
As examples:
- A grid is shown on the page - for each line in the grid, there is a "Update" button. When this button is pressed, an update page must be shown - with pre-filled values from the record shown in the grid line. In this case it is necessary to transfer the identification of the record shown in the line from the PageGenerator to the EventHandler. Otherwise the EventHandler has no information about which record to show/update.
- The PageGenerator contains a grid, only a limited number of records must be shown in the grid, a "Next" button is to be used to show the next segment of the records. After the grid is loaded, the identification of the last record is written as a parameter (using the SetParm API), this information is then used to position the list when "Next" is pressed.
- In the PageGenerator a complex/time consuming calculation has been made to show a value on the page. When a button is pressed, a record must be updated with this value. To avoid having to recalculate the information should be transferred from the PageGenerator to the EventHandler.
After investigating which pages and events you'll need for your business process, you will be ready to continue with the actual development.
3. Create functions in 2E
The name of the EventHandler program object has to correspond with the Event ID specified when making the template.
In many 2E applications you will just let 2E assign these program names - so before proceeding with the creation of the templates, it is beneficial to create the EventHandler functions in 2E.
As you at this point in time know all of the pages and events necessary, you might as wll just create all of the functions right away.
Create ProcessEntryPoint:
For a business process you must create exactly one ProcessEntryPoint function.
- Create the ProcessEntryPoint by going to the 2E "Edit functions" panel for the file where you want the PageGenerator function to be scoped and press F21.
- Select the 2E function template "W2E/ProcessEntryPoint.
- Assign an appropriate name to the function.
Create PageGenerators:
For each page you identified under step 1, create one PageGenerator function. This function is used to populate all of the fields shown on the template.
If the Page does not contain a grid:
- Create the PageGenerator by going to the 2E "Edit functions" panel for the file where you want the PageGenerator function to be scoped and press F21.
- Select the 2E function template "W2E/PageGenerator".
- Assign an appropriate name to the function.
If the Page does contain a grid:
- Create the PageGenerator by going to the 2E "Edit functions" panel for the file where you want the PageGenerator function to be scoped and press F21.
- Select the 2E function template "W2E/GridPageGenerator
- Assign an appropriate name to the function.
Please note that in addition to creating the PageGenerator function with the specified name, another function W2E/LoadGrid is created (if it does not already exist as a function scoped by the file). If you want to have more than one GridPageGenerator scoped by a file - and you do not want these GridPageGenerators to use the same function to load the grid - you should rename the W2E/LoadGrid function after each creation of each GridPageGenerator.
Create EventHandlers:
For each event you identified under step 2, create one EventHandler (if the same event occurs for more than one page, only create one EventHandler function for this event).
- Create the EventHandler by going to the 2E "Edit functions" panel for the file where you want the EventHandler function to be scoped and press F21.
- Select the 2E function template "W2E/EventHandler".
- Assign an appropriate name to the function.
4. Create Templates using the PageModeler
For each PageGenerator, you need to create an HTML template file that will provide the basis for the web pages that will be generated and sent to the browser.
You create a first cut version of these HTML templates by using the PageModeler application.
The PageModeler is found in the administration menu - under the heading RPGDeveloper.
Create HTML template using the PageModeler
For each identified page
Create a new page in the PageModeler.
Please note that the name you specify for the page will be the text you will use to refer to the template in the 2E functions. After the page is created you will be on the PageStructure page - this is where you define the content of the page.
For each output field identified for the detail region of the page:
Select the Page and press "Add".
Select Field.
On the "Add Field" page enter the information about a replacement marker (the text will be used to identify the field in the template and in the program) - the label (corresponds to left hand side text in the 2E screen editor) - and optionally some test data.
For each event which belongs to the detail region:
Select the Page and press "Add". Select Event - and on the "Add Event" Page enter the information about the Event ID (The object name of the EventHandler program you have created in step 3) - select whether the event should be presented as a button or a link - enter the label (which is the text that will be shown on the button/link).
For each input field you have identified as necessary in step 2
(Only the input fields which the user must enter values into - not the ones where values should be transferred from the PageGenerator to the EventHandler)
Select the event. Press Add. On the "Add Field" page enter information about a replacement marker (the text will be used to identify the field in the template and in the program) - the label (corresponds to left hand side text in the 2E screen editor) - the length of the input field - and optionally some test data.
If you have identified a need for a grid:
Select the page and press '"Add". Select Grid - enter the number of rows you as default want to load to the grid.
For each output field you have identified as belonging to a grid in step 1:
Select the Grid in the structure. Press "Add". Select "Field". On the "Add Field" page enter the information about a replacement marker (the text will be used to identify the field in the template and in the program) - the label shown for the field - and optionally some test data.
For each event you have identified as belonging to the grid in step 2:
Select Grid and press "Add". Select "Event". On the "Add Event" page enter the information about the Event ID (The object name of the EventHandler program you have created in step 3) - select whether the event should be presented as a button or a link - enter the label (which is the text that will be shown on the button/link).
For each input field you have identified as necessary in step 2:
(Only the input fields which the user must enter values into - not the ones where values should be transferred from the PageGenerator to the EventHandler).
Select the event. Press Add. On the "Add Field" page enter information about a replacement marker (the text will be used to identify the field in the template and in the program) - the label shown for the field - the length of the input field - and optinally some test data.
After this, the definitions are finished - to create the template press "Create/View template" on the Page Structure page.
On the "Create Template" page, select the folder, where you want to place the generated template file. Unless you have other preferences, select the folder "pagemodeler".
Press "Create" - and the template is created and deployed in the selected folder. This means that the template is immediately ready for use.
The exact position of the template in the IFS is shown after the template is created - and you have the possibility to preview the template.
5. Code PageGenerators
To get an overview of the content of the page, and thereby of the fields you need to assign values for, go to the PageModeler, Press the button "Page Structure" for the page you are going to make the PageGenerator for. On the Page Structure Page, Press "Developer Info" - print the resulting page.
This gives you an overview over the fields and events on the page, which you can use to structure your PageGenerator program as follows:
Assign template name:
Start by changing the assignment of LCL.W2E/TemplateName from CND.CHANGE THIS to the value specified in the field Page Name under the section Page information.
In many situations, you will want to receive a number of input parameters for a PageGenerator - add these fields to the parameter definition of the function as needed.
For each field shown under Output fields:
Place this code in the sequence "Set values for output fields".
Find the value you want to show for the field (read it from the database, receive it as an input parameter, calculate the value etc.).
If necessary, convert the value to a character string - and format this string to a suitable format.
- If you want to show a numeric field, you can use the Numeric2String API to format the numeric field and convert it to a character string.
- If you want to show a date field, you can use the Date2String API to format the date and convert it to a character string.
Call the SetOutput API with the following parameters:
Parameter Value W2E/TemplateName LCL.W2E/TemplateName W2E/TypeName Replacement marker for the field W2E/TypeValue The formatted string value W2E/HtmlCharEsc CND.*Blank
For each event shown under Events:
For each input field available for the user:
Place this code in the sequence "Set initial value for input fields".
If you want a value to be shown in the input field as the page is loaded (default/initial value for the input field):
Find the value, you want to show for the input field.
If necessary, convert the value to a characterstring and format the string.
- If you want to show a numeric field, you can use the Numeric2String API to format the numeric field and convert it to a character string.
- If you want to show a date field, you can use the Date2String API to format the date and convert it to a character string.
Call the SetOutput API with the following parameters:
Parameter Value W2E/TemplateName LCL.W2E/TemplateName W2E/TypeName Field replacement marker for the input field scoped under the event W2E/TypeValue The formatted string value W2E/HtmlCharEsc CND.*Blank For each parameter, which it is necessary to transfer from the PageGenerator to the EventHandler (identified under step 2):
Convert the value to a character string if necessary - as the value is not shown to the user, it should not be necessary to format it.
Call the SetParm API with the following parameters:
Parameter Value W2E/TemplateName LCL.W2E/TemplateName W2E/EventID Event ID for the event W2E/TypeName The Name you will use to fetch the value in the EventHandler (does not occur in developerinfo - as this field is never written to the page) W2E/TypeValue The value you want to transfer to the EventHandler (as a character string)
If you have a grid do the following:
When you have a grid, you have used the W2E/GridPageGenerator 2E function template to create the PageGenerator function.
This will also have created a function W2E/LoadGrid scoped under the same file as the PageGenerator.
Change the access path for this function to one that corresponds to the ordering you want for the records shown in the grid.
If you want to be able to position the start record of the grid, change the parameter interface so that the keys for the access path is used as POS parameters (you can of course also restrict using RST parameters - just as for any othe RTVOBJ function).
In the GridPageGenerator, map these parameters with fields containing the position. Keep the mapping of the W2E/TemplateName with LCL.W2E/TemplateName.
In the User point "Process Data Record" in the W2E/LoadGrid function, do the following:
For each field shown in the table Grid output fields:
Place the code in the sequence "Set values for output fields in the grid".
Find the value you want to show for the field.
If necessary, convert the value to a character string (non character data) - and format this string to a suitable format.
- If you want to show a numeric field, you can use the Numeric2String API to format the numeric field and convert it to a character string.
- If you want to show a date field, you can use the Date2String API to format the date and convert it to a character string.
Call the SetGridOutput API with the following parameters:
Parameter Value W2E/TemplateName PAR.W2E/TemplateName W2E/Gridrow LCL.W2E/Gridrow W2E/TypeName Replacement marker for the field W2E/TypeValue The formatted string value W2E/HtmlCharEsc CND.*Blank For each event shown in the table Grid events:
Place the code in the sequence: "Set initial values for input fields for events".
For each input field available for the user:
If you want a value to be shown in the input field as the page is shown (default/initial value for the input field):
Find the value you want to show for the input field.
If necessary, convert the value to a characterstring and format the string.
- If you want to show a numeric field, you can use the Numeric2String API to format the numeric field and convert it to a character string.
- If you want to show a date field, you can use the Date2String API to format the date and convert it to a character string.
Call the SetGridOutput API with the following parameters:
Parameter Value W2E/TemplateName PAR.W2E/TemplateName W2E/Gridrow LCL.W2E/Gridrow W2E/TypeName Replacement marker for the field W2E/TypeValue The formatted string value W2E/HtmlCharEsc CND.*Blank For each parameter, which it is necessary to transfer from the PageGenerator to the EventHandler (identified under step 2):
Convert the value to a character string if necessary - as the value is not shown to the user, it should not be necessary to format it.
Call the SetGridParm API with the following parameters:
Parameter Value W2E/TemplateName PAR.W2E/TemplateName W2E/Gridrow LCL.W2E/Gridrow W2E/EventID Event ID for the event W2E/TypeName The Name you will use to fetch the value in the EventHandler (does not occur in developerinfo - as this field is never written to the page) W2E/TypeValue The value you want to transfer to the EventHandler (as a character string)
6. Code ProcessEntryPoint function
In the ProcessEntryPoint function created in step 3, add a call to the PageGenerator function for the page you have identified as the first page to show in the business process.
Add this just after the comment "Enter call to initial PageGenerator".
If there are several possible first pages you must retrieve the necessary information for choosing which page to show and code the logic necessary for the choice in this function.
7. Code EventHandler functions
For each of the EventHandler functions created under step 3, you must code the logic for:
- Retrieving the values set by the PageGenerator
- Retrieving the values entered by the user
- Handling this information.
- Call the PageGenerator for the page you want to show to the user.
You can find the definitions for the EventHandler on the developer info for the page(s) it is included in.
In the EventHandler you must code the following logic:
For each field made available by the PageGenerator (by calling SetParm):
Place this code in the sequence "Retrieve parameters set by the PageGenerator" before the pre-defined call to the ValidateParm function.
Call the GetParm API with the following parameters
Parameter Value W2E/TypeName The TypeName used by the PageGenerator W2E/TypeValue The field you want to retrieve the value into (Output) The pre-defined call to ValidateParm ensures that the values for the parameters are the same as when the PageGenerator wrote them.
For each input field defined for the event (each field shown in the Developer Info Table for the event):
Place the code in the sequence "Retrieve user input".
Call the GetInput API with the following parameters:
Parameter Value W2E/TypeName The Replacement marker specified for the field W2E/TypeValue The field you want to retrieve the value into (Output)
After having done these two steps, you have all of the information, that the event delivers, available in the program.
Enter any business logic necessary for the handling of the event (update records, calculate/read new values to show etc.). Enter this in the sequence "Business logic"
Finally, make a call to the PageGenerator function that creates the page you want to show to the user. Enter this call in the sequence "Call Page Generator"
It is quite common that there is a number of possible PageGenerators to call dependent on the executed business logic (E.g. one in error situations - and one for successful execution).
8. Generate and build
Generate the source and create the objects for all of the functions you have created.
9. Deploy objects
The easiest way to do this is to add the 2E generation library to the library list for the application service jobs (change the Job Description "Express" to include the library in the library list).
As the templates are automatically deployed, and the jobs with the change of the job description will have access to the program objects, the business process should be available right away.
Please note that if you have changed objects, you will have to stop and start the jobs used to service the webapplication before you can be sure that the new versions are used (use the STOP/START commands).
One important thing is that if you just add the generation library to the library list - you should change the Site Setting "Library for created events" to the 2E generation library. (The change is done using the administration interface menu item: Sites->Site Settings).
10. Define process in the administration interface
To make it possible for the Websydian Express framework to call the business process, you have to define it in the administration interface.
Go to Processes -> Maintain Processes
Create a new Business Process (keep the "Create default presentation" checked on the insert page). The Process ID must be the implementation name of your ProcessEntryPoint function (created in step 6).
Go to Site Structure -> Maintain Site Structure
In the tree structure, select the menu where you want to show the business process as a menu item. (Note the sequence of the other menu items for this menu - based on these sequences, and where you want to place the new menu item in the menu, you can find out which sequence to use for the new menu item).
Press "Add" (while the menu is selected") - Select Business Process and New, Press Next.
Enter information about the menu item (text shown in the menu, authorization needed to see and use the menu item and the sequence specifying where the menu should). One important thing to select is the frame which you want the business process to populate. Normally looking at the other menu items scoped by the same menu will give the best idea of which frame to select.
Press Next.
Select the presentation created for the new business process (will have the same name you specified for the business process).
Press Finish on the page shown after the presentation is selected.
11. Test
Reload the site (press Ctrl-F5) - use the new menu item to activate the business process.
Troubleshooting:
In some cases the developed business process will not exhibit the expected behavior. There are a number of ways you can obtain information about why the problem occurs:
- iSeries joblog
Just as for any other application running on the iSeries, the joblog is one of the major sources of information about any errors encountered during the execution of the business Process.
When the START command is used to start Websydian Express, a number of jobs are started. One or more of these are called EXPRESSAS. These are the jobs running the application. Each request will be handled by one of these jobs.
Please note that it is in no way guaranteed that all requests from one session will be handled by the same job. This means that you should check the joblogs for all of the jobs to be sure to find all of the problems encoutered.
In almost any case, where no page is sent to the browser, it will be the iSeries joblogs that you need to look at.
- Websydian Express Message Log
The Websydian Express runtime will in some cases encounter error situations that need to be reported. These errors are written to the message log. The message log is available through the administration interface - menu item: Utilities -> Message Log.
Among the errors typically reported to the message log are:
- Templates can't be found in the IFS
- ProcessEntryPoint defined for the business process can't be found in the library list/error occurs calling ProcessEntryPoint.
- EventHandler for an activated event can't be found in the library list/error occurs calling EventHandler.
In most cases, where a generic error message ("An error occurred...") is sent to the browser, the message log will contain information about the reason for the error.
- /(DUMP) replacement marker
If you do not get the information you expected written to the page, you can insert the /(DUMP) replacement marker in the template where you do not get the expected information.
When the WritePage function is called for the template, the DUMP replacement marker will be replaced by a list of all values that has been written to the page (using the SetOutput, SetGridOutput, SetParm, SetGridParm APIs).