forms-to-apex WMS ID - 11716 (#187)

* forms-to-apex

* oci-doc

forms-to-apex/1-analyze-sample-forms/analyze.md

@@ -0,0 +1,135 @@
+# Analyze the Sample Forms [Study]
+
+## Introduction
+
+This Lab analyses your current Forms environment and identifies the important business logic. The first part of the Lab provides an overview guide on understanding forms modules and how they compare to APEX modules. The second part provides the sample forms used in this live lab.
+
+*Note: This Lab assumes you have an Oracle Forms setup in your environment.*
+
+Estimated Time: 5 Minutes
+
+### Objectives
+
+In this lab, you:
+
+- Understand the current business logic in Oracle Forms and how to map it to Oracle APEX components.
+
+## Task 1: Analyze Forms Business Logic
+
+To modernize from Oracle Forms to APEX, you must understand the current business logic of your forms and where they are implemented. This is key for deciding how to adapt them to the APEX environment. The rule of thumb is always to push as much business logic as possible into the Oracle Database.
+
+For example, the business logic in Oracle Forms resides in the triggers and program units. You can incorporate this logic into Oracle APEX as SQL or PL/SQL code that invokes database packages, procedures, or functions. The same applies to database objects, which do not need alteration when transitioning from Forms to APEX.
+
+However, in Oracle Forms, business logic is also intertwined with user interface items such as go\_item, set\_item\_property, etc. In this case, separating and pushing logic to the database is impossible. In some cases, pushing the business logic of the triggers and program units into the database might be challenging.
+
+Analyze and map the logic to the appropriate APEX component. The APEX environment natively handles multiple events and logic blocks through processes, computations, and validations. Understand how these components work and the customizations you can apply to them. This understanding prevents you from rewriting code and business logic that APEX's components can handle automatically.
+
+You can add business logic to Forms through the PL/SQL attached libraries, which you can usually call from form modules. When mapping to APEX, add this logic as an application-level process that can be called from any application's pages. Additionally, you may find a plug-in to install that achieves the purpose of your business logic and extends your application's functionality. Plug-ins are available on:
+
+- [apex.oracle.com](https://apex.oracle.com/en/solutions/apps/)
+- [apex.world](https://apex.world/ords/f?p=100:700)
+
+Understanding how the mappings work on data blocks is also essential. In Forms, you can map data blocks into pages and page regions in APEX. There are different types of data blocks on Forms:
+
+1. **Single Record Blocks**:
+In Forms, you may use a single record block for data queries and modifying returned records. In APEX, you generally map Oracle Forms blocks that are insertable, updatable, and have a primary key to an interactive report with a form or an editable Interactive Grid. The edit link on the interactive report allows access to a specific record for updating or deleting, and the interactive report lets you query the entries. An editable interactive grid lets you change several rows simultaneously without navigating to another form page.
+
+2. **Tabular Forms**:
+Tabular Forms blocks in Forms map to an interactive grid in APEX, allowing you to edit each item later as needed (select list, text field, number field, etc.).
+
+3. **Master Detail Blocks**:
+In Forms, master detail blocks highlight relationships between data blocks. In APEX, you can map this through the master detail region. The child region represents the "detail," and the parent region represents the "master," which can be a page region such as an interactive grid. Both regions connect through the foreign key relationship between the columns. You can define several child relationships deep and any number of child relationships wide.
+
+4. **Non-Database Block**:
+Any block in Forms not associated with a database table or view is a non-database block. These blocks usually hold menus, lists, buttons, and other components. In APEX, we define these components based on their type. For example, the page designer defines buttons, while shared components define navigation menus.
+
+## Task 2: Analyze Sample Forms
+
+To put the previous guidelines into perspective, let's see how we can analyze the business logic and components of one of our sample forms. For this example, we will use the customer's form.
+
+[Download the Sample Forms](https://c4u04.objectstorage.us-ashburn-1.oci.customer-oci.com/p/EcTjWk2IuZPZeNnD_fYMcgUhdNDIDA6rt9gaFj_WZMiL7VvxPBNMY60837hu5hga/n/c4u04/b/livelabsfiles/o/labfiles/sample_forms.zip)
+
+We start by reviewing the existing components in the form to analyze which can be migrated to APEX, which will be mapped to APEX components, and which will be removed or rewritten.
+
+1. **Data Blocks**: Five data blocks, including **S\_CUSTOMER1** and **S\_CUSTOMER**, are associated with the **S\_CUSTOMER** table. The **S\_CUSTOMER** block is editable and allows CRUD operations, so you can map it into the Form item in APEX to enable the same operations. However, the **S\_CUSTOMER1** block isn't editable, so you can't handle it the same way.
+
+    The remaining three blocks **(CONTROL, NAV\_CONTROL, NAVIGATOR)** are non-database blocks that handle navigation in Forms and control the tree region, which isn't applicable in APEX.
+
+    ![Blocks](images/data-blocks.png " ")
+
+2. **Triggers**: The Customer's form contains multiple triggers, but we are now mainly focused on the triggers associated with the S\_CUSTOMER block.
+
+    The first trigger is **POST\_QUERY**. This trigger isn't translatable into APEX, as APEX automatically incorporates the trigger logic in the form's creation process. This is where the form items are initialized. Initialization options include initializing the form region items or retrieving data from the region source using the primary key value(s).
+
+    The second trigger is **WHEN-MOUSE-DOUBLECLICK**. This trigger executes the procedure EDIT\_TEXTITEM, which invokes a pop-up window editor for the COMMENTS column. When mapping to APEX, we can ignore this trigger since APEX will automatically initialize this COMMENTS column in the form.
+
+3. **LOVs**: There is only one list of values created which is **SALES\_REP\_LOV** executing the above SQL statement.
+
+    ![LOVs](images/lovs1.png " ")
+
+    ![LOVs SQL Query](images/sql-query1.png " ")
+
+    In APEX, the LOV is created automatically with the form's creation. However, it may not display the intended values as in the SQL query.
+
+    To change this in **Oracle APEX**:
+
+    - Navigate to **App Builder** and select your application.
+
+    - Click **Shared Components**.
+
+    - Under **Other Components**, click **List of Values**.
+
+    - Click the list of values and update the name and SQL Query.
+
+    *Note: Remember that you can define additional display columns for item types that support multiple display columns.*
+
+   ![LOVs SQL Query](images/sales-rep-lovs1.png " ")
+
+4. **Alerts**: We have two alerts in the customer's form. The first alert, **DELETE\_ALERT**, is automatically created when the form is created in APEX, and you can customize the displayed message:
+
+    To customize the display message in Oracle APEX, follow the following steps:
+
+    - Navigate to **App Builder** and select your application.
+
+    - Click **Shared Components**.
+
+    - Under **Other Components**, click **Shortcuts**.
+
+    - Click **Create**.
+
+    - Create shortcut **From Scratch**.
+
+    - Click **Next**.
+
+    - For Name, enter **DELETE\_ALERT**.
+
+    - For Type, select **Text with JavaScript Escaped Single Quotes**.
+
+    - For a shortcut, enter the original message.
+
+    - Click **Create**.
+
+    You have created the message and need to update the shortcut in the APEX Form.
+
+    - Go to the **Customers** form page.
+
+    - In the left pane, click the page name.
+
+    - Navigate to property editor and update **Function and Global Variable Declaration** to var htmldb\_delete\_message='"DELETE\_ALERT"';
+
+    The second, **CONFIRM\_REVERT**, is handled natively by APEX through the warn on unsaved changes property, which can warn users when navigating away from the page with unsaved changes.
+
+    ![Alerts](images/alerts1.png " ")
+
+5. **Program Units**: The customer form contains seven program units. However, we cannot map them in our APEX app because either APEX handles them natively during form creation or they are not applicable.
+
+    ![Program Units](images/program-units1.png " ")
+
+## Summary
+
+This Lab provides a comprehensive approach to understanding and migrating Oracle Forms components to Oracle APEX, ensuring a smooth modernization process by leveraging APEX's native capabilities and customization options.
+
+## Acknowledgements
+
+- **Author** - Monica Godoy, Senior Principal Product Manager ; Ankita Beri, Product Manager; Paolo Paolucci, Data Development Specialist; Victor Mendo, Data Development Specialist
+- **Last Updated By/Date** - Ankita Beri, Product Manager, July 2024

forms-to-apex/2-mapping-forms-to-apex/2-mapping-forms-to-apex.md

@@ -0,0 +1,104 @@
+# Mapping Oracle Forms components to APEX [Study]
+
+## Introduction
+
+This lab focuses on understanding how to map Oracle Forms components to the most appropriate APEX components to achieve similar functionality. The lab provides guidelines for comparing Oracle Forms modules with those in APEX, noting that mapping may not always be a direct 1:1 relation.
+
+Estimated Time: 5 Minutes
+
+### Objectives
+
+In this lab, you:
+
+- Understand how to map Oracle Forms components to Oracle APEX components effectively.
+
+## Task 1: Examine Form's Component
+
+There are three main approaches to take when mapping modules from Forms to APEX:
+
+- Discard Forms component/item.
+- Move the component's logic into the database.
+- Recreate components as an APEX item.
+
+In the following sections, we will examine each of Form's components to determine how they best map into APEX.
+
+1. **Alerts**:
+You can store an alert message as a text message in shared components in an APEX application. Text messages allow you to build translatable text strings with substitution variables that PL/SQL packages, procedures, and functions can call.
+
+    You can also map alerts into [Dynamic Actions](https://docs.oracle.com/en/database/oracle/apex/24.1/htmdb/managing-dynamic-actions.html#GUID-7E564715-E963-44AA-B620-5FFB5EFA62EE), which execute to display an alert dialog and message when an event occurs.
+
+    Another native approach for initiating alerts is to enable the [Confirmation option on buttons](https://docs.oracle.com/en/database/oracle/apex/24.1/htmdb/creating-buttons.html#GUID-F6DA76D1-2020-4930-8D26-12D0A3497C8E).
+
+    ![Alerts](images/alerts.png " ")
+
+2. **Blocks**:
+Blocks will usually correspond to a region type in APEX. As discussed in Lab 1, blocks are either associated with a database object or not. The block type and the data source type determine which [region type](https://docs.oracle.com/en/database/oracle/apex/24.1/aeacc/regions.html) we map to in APEX. For example, if in Forms, we have a report based on a view, this can be mapped to an interactive report region with data source view.
+
+    ![Blocks](images/blocks1.png " ")
+
+    ![Blocks](images/blocks2.png " ")
+
+3. **Canvases**:
+In Oracle Forms, the canvas is where the graphical user interface (GUI) or background of the Form is drawn. In Oracle APEX, the engine constructs the appearance of each page in an application using templates. [Templates](https://apex.oracle.com/pls/apex/r/apex_pm/ut12/templates) define how pages, page controls, and page components are displayed.
+The mapping also involves identifying the [page type](https://docs.oracle.com/en/database/oracle/apex/24.1/htmdb/managing-pages-in-an-application.html), which defines the page's overall functionality and appearance.
+
+    ![Canvases](images/canvases.png " ")
+
+4. **Coordinates**:
+Depending on the coordinate system used in a Forms application, coordinates can be expressed in actual units such as inches, centimetres, and pixels. APEX has built-in [responsiveness](https://docs.oracle.com/en/database/oracle/apex/24.1/htmdb/understanding-the-universal-theme.html) that adjusts based on screen size. Page items and regions are adjusted in size and positioning depending on the screen to render responsively. Hence, APEX doesn't support the coordinates system as it is based on a grid layout that determines how elements are on a page.
+
+5. **Editors**:
+In Forms, editors provide standard editing features, including search and replace and cut, copy, and paste for text items. These can be mapped to the rich text editor page item.
+
+    ![Editors](images/editors.png " ")
+
+6. **Events**:
+Events specify specific actions to occur based on an event that occurred in Forms. In APEX, we can define this behavior using dynamic actions and events. Dynamic actions events allow us to specify client-side actions based on events.
+
+    ![Events](images/events.png " ")
+
+7. **List of Values**:
+The values in Forms can be directly mapped to the [List of Values](https://docs.oracle.com/en/database/oracle/apex/24.1/htmdb/about-lists-of-values.html) in APEX. The values can be defined statically or dynamically from the database. Using SQL queries, we can specify the display and return values of list items. These lists can be reused across the entire application.
+
+    ![List of Values](images/lovs.png " ")
+
+8. **Object Groups**:
+In Forms, object groups are used to share components between multiple forms. These objects are collections of controls, including blocks, canvases, alerts, etc). In APEX, these are mapped to [Shared Components](https://docs.oracle.com/en/database/oracle/apex/24.1/htmdb/shared-components-page.html).
+
+    ![Object Groups](images/object-groups.png " ")
+
+9. **Parameters**:
+A parameter is a variable whose value can be set at runtime. Parameters are beneficial for modifying SELECT statements and setting PL/SQL variables at runtime. In APEX, this can be mapped to the [SET_PARAMETER](https://docs.oracle.com/en/database/oracle/apex/24.1/aeapi/SET_PARAMETER-Procedure.html) procedure in the APEX\_INSTANCE\_ADMIN package, which provides utilities for managing an Oracle APEX runtime environment.
+
+10. **Program Units**:
+As discussed in Lab 1, program units implement business logic in Forms, which can be incorporated into APEX as a PL/SQL package, [page process, computation, or validation](https://docs.oracle.com/en/database/oracle/apex/24.1/htmdb/managing-computations-validations-and-processes.html).
+
+11. **Property Classes**:
+In Forms, a property class is a named object that contains a list of properties and their settings. An object based on a property class can inherit the settings of any property in that class. Property classes are not used within the generation of APEX applications. However, the concept is mapped to how a [theme](https://docs.oracle.com/en/database/oracle/apex/24.1/htmdb/about-themes.html#GUID-DA2773A1-4291-4C1F-B2DD-C3AC822BCCF0) is defined as a named collection of templates used to create the user interface of an application.
+
+    ![Property Classes](images/user-interface.png " ")
+
+12. **Record Groups**:
+In Forms, record groups to define the query for a list of values. As mentioned in the "List of Values" mapping, this is achieved in APEX by mapping it to a dynamic LOV and defining the SQL query for the values.
+
+    ![Record Groups](images/record-groups.png " ")
+
+13. **Triggers**:
+In Forms, a trigger is an event handler written in PL/SQL to augment the default processing behavior. As discussed in Lab 1, the trigger logic can be incorporated into APEX as a computation, validation, or PL/SQL process after creating the initial application to map the business logic.
+
+14. **Visual Attributes**:
+Visual attributes are the font, color, and pattern properties you can set for form and menu objects appearing in the Forms application's interface. You can style your applications using the default cascading style sheets (CSS) installed with APEX or by uploading your own CSS files.
+
+    ![Visual Attributes](images/visual-attributes.png " ")
+
+15. **Windows**:
+The window in Forms is the container for all visual objects that comprise the application, including canvases. Windows maps to a page in APEX since the page holds all of the visual objects for an application.
+
+## Summary
+
+This lab provides comprehensive guidelines for mapping various Oracle Forms components to APEX, ensuring functionality is retained or improved during modernization.
+
+## Acknowledgements
+
+- **Author** - Monica Godoy, Senior Principal Product Manager ; Ankita Beri, Product Manager; Paolo Paolucci, Data Development Specialist; Victor Mendo, Data Development Specialist
+- **Last Updated By/Date** - Ankita Beri, Product Manager, July 2024