Preparation Tool for New Base Server Framework Architecture

Note: This feature will be available with IFS Cloud 25R2 GA. However, any preparation work required needs to be done starting from EA.

To simplify the transition process to the new Base Server Framework which is based on Oracle EBR, a set of preperation tasks are automated and implemented in the EBR Preparation Tool. This tool is integrated with IFS Developer Studio, allowing developers to run it in their customer repositories to automatically apply certain preparation steps required to make their codebases EBR compliant.

It is important to note that, while the tool automates part of the work, developer review remains mandatory to ensure the correctness of the changes.

The EBR Preparation Tool currently automates three types of preparation tasks:

Note: This is only true if the customer has opted for the Uptime Maximizer.

• Updating basedOn Entities

• Updating table names in .storage files

• Code registration for .ins and .drp files

Based-on Entity Update

Based-on entities are implemented with a parent - child relationship, where the parent entity defines the table structure and one or more child entities reuse the same table for storage. These relationships are defined in the child entity file through a basedOn attribute pointing to the parent, so the child entities are aware of the parent but the parent isn't aware of the associated child entities. The parent entity creates the table in its .cre file, while child entities add their additional columns in their own .cre files.

While making the tables EBR-compliant, each table was mapped to an editioning view, which requires the parent entity to have knowledge of all table columns, including those from its child entities during its creation time. To enable this, a new syntax is introduced to register child entities in the parent using the basedOnEntities property, and a new code generation property, GenerateStorageFile "no"; is added to child entities to prevent duplicate table creation.

To implement this change, you need to make two manual changes to based-on entities.

1. Child entities have to be registered in the parent entity using the basedOnEntities block:

basedOnEntities {   
  includeBasedOnAttributes <Component>/<EntityName>;
} 

1. Child entities require a new code generation property, GenerateStorageFile:

codegenproperties {
  DbTableName         "<ParentTableName>";
  GenerateStorageFile "no";
}

The preparation tool automates these steps by scanning all .entity files in the codebase, identifying parent - child relationships, and inserting the necessary attributes into the corresponding files.

Note: Since precedence rules depend on the order in which child entities are listed in the parent entity, conflicts may arise if the same column is defined by multiple child entities. The tool does not have the necessary context to determine the correct order automatically. Therefore, it is the developer’s responsibility to review the child entities identified by the tool and arrange them in the appropriate order, following the provided guidelines for based-on entities.

Error Messages and Reasons

Error Message	Reason
Failed to read entity file | <reason>	The entity file could not be read, possibly due to permission issues or unexpected I/O errors.
Parser configuration error | <reason>	Failed to create XML document parser, likely due to a runtime error.
XPath evaluation error | <reason>	XPath evaluation failed, possibly due to a runtime error.
Failed to parse entity document | <reason> Example: Failed to parse entity document | Content is not allowed in prolog.	An unexpected error occurred while parsing the XML file. Example: Invalid XML file. Possibly an obsolete entity file.
Failed to parse entity | Entity name not found	The entityname element was missing or empty in the file.
Failed to parse entity | Component name not found	The component element was missing or empty in the file.
Failed to parse based-on attribute | Component and model name are required	The file contains basedOnEntities, but one or both of the component or entity names in includeBasedOnAttributes are missing or empty.
Failed to link child entity. Parent entity 'ParentEntity' not found or has parsing errors	The declared parent entity was not found in the scanned entity list. The file may be missing or incorrectly parsed due to errors. Verify that the parent entity exists and is free of syntax issues.
Failed to link child entity. Multiple parent entities named 'ParentEntity' found (likely due to core entity customization in cust layer). Please verify manually	Multiple entity files with the same parent entity name were detected (likely due to core entity customization in the cust layer). Since the tool cannot determine the correct parent, this must be resolved manually.
Failed to link child entity. Circular reference detected in parent entity hierarchy at 'ParentEntity'	A circular parent–child reference was detected. This occurs when a parent entity indirectly refers back to one of its child entities as its parent. Such cases must be manually reviewed and corrected.
Child entity validation failed. Invalid generateStorageFileProperty value 'yes', expected 'no'	The child entity already defines the GenerateStorageFile property, but its value is invalid. The expected value is 'no'.
Parent entity validation failed. Unexpected BasedOnAttribute(s) found: [Component/ChildEntity]	The parent entity defines a basedOnEntities section, but some listed child entities do not have a valid basedOn relationship with the parent or could not be identified due to parsing errors. These must be manually verified.
Parent entity validation failed. Partially processed file, missing BasedOnAttribute(s): [Component/ChildEntity]	The parent entity defines a basedOnEntities section, but some child entities with a valid basedOn relationship are missing. Since the tool cannot determine whether this omission was intentional, the file is skipped and requires manual review.
Child entity validation failed. Parent entity 'ParentEntity' has errors, cannot proceed with child	The child entity has no errors, but its parent entity contains issues. To ensure correctness, the child entity was not updated.
Parent entity validation failed. One or more child entities have errors, cannot update parent	The parent entity has no errors, but one or more of its child entities contain issues. To ensure correctness, the parent entity was not updated.
Failed to process entity file | <reason>	The entity file could not be processed, possibly due to permission issues or unexpected I/O errors.
Entity file content cannot be empty	The entity file is empty. This may indicate unexpected I/O errors or that the file was modified while the tool was running.
Failed to find XML element position to insert <BASED_ON_ENTITIES>	The tool expected to insert the basedOnEntities section before the attributes section but could not locate it in the file. Manual review is required.
Failed to find XML element position to insert <CODE_GENERATION_PROPERTIES>	The tool expected to insert codegenproperties at the top of the file but could not determine the correct position in the XML document. Manual review is required.

Fixing Storage Files

The purpose of this is to ensure the compliance of all the .storage files containing table/constraint/key declarations with the new EBR standards.

The following scenarios will be taken care of in the .storage files by this tool.

In table declarations,

1. Tables that end with _TAB are replaced with _RTB.

2. Tables that end with _TMP and _VRT are appended as _TMP_RTB, _VRT_RTB, followed by EDITIONED AS <original name ended with _TMP or _VRT>.

3. Table names that have suffixes other than the above-mentioned ones, are appended with _RTB.

In the Constraint / Key / Index statement, the table name (which is always followed by IS keyword) is replaced by the appropriate table name as explained above.

Given below are a few examples of the before and after scenarios:

Statement Type	Before	After
Table	TABLE accounting_text_tab IS	TABLE accounting_text_rtb IS
Table	TEMPORARY TABLE accrul_session_pid_tmp IS	TEMPORARY TABLE accrul_session_pid_tmp_rtb EDITIONED AS accrul_session_pid_tmp IS
Table	TEMPORARY TABLE accrul_session_pid_vrt IS	TEMPORARY TABLE accrul_session_pid_vrt_rtb EDITIONED AS accrul_session_pid_vrt IS
Table	TABLE ac_am_str IS	TABLE ac_am_str_rtb IS
Constraint	UNIQUE CONSTRAINT accounting_seq_no_rk IS accounting_seq_no_tab (rowkey);	UNIQUE CONSTRAINT accounting_seq_no_rk IS accounting_seq_no_rtb (rowkey);
Primary Key	PRIMARY KEY accrul_session_pid_pk IS accrul_session_pid_tmp (session_id, posting_combination_id);	PRIMARY KEY accrul_session_pid_pk IS accrul_session_pid_tmp_rtb (session_id, posting_combination_id);
Index	INDEX afp_item_ix1 IS afp_item_tab (contract_no);	INDEX afp_item_ix1 IS afp_item_rtb (contract_no);
Primary Key	PRIMARY KEY ac_am_str_allowed_comb_pk IS ac_am_str_allowed_comb (str_code, str_code_prod, control_type, control_type_prod, allowed_code_part);	PRIMARY KEY ac_am_str_allowed_comb_pk IS ac_am_str_allowed_comb_rtb (str_code, str_code_prod, control_type, control_type_prod, allowed_code_part);

Note: Since this is done by pattern matching and substitution there will be no logical errors popping up - in case of errors, they can only be IO exceptions.

Running the Tool

1. Open Developer Studio - Launch Developer Studio and open the workspace containing the project or components you want to prepare.

2. Right-Click on the Target - In the Project Explorer, locate the project or individual components you wish to run the tool on. Right-click on the item and select, Run -> 25R2 Framework Preparation**.

   

   

3. Enter Username - Upon launching the tool, a prompt will appear requesting your username.

   Example

   --SAFE_FOR_ONLINE_DEPLOYMENT(2025-09-01, your_username, PRE_25R2_PATCH_REGISTERED)
   

   

4. View the Preparation Report - Once the tool runs, a report table will appear summarizing the results. This includes:

   • File – The name of the file scanned.
   • Modified – Indicates whether the file was updated by the tool.
   • Preparation Status – Shows whether the preparation was successful.
   • Message - Provides additional context. If the preparation was not successful, this column will contain details about what went wrong and what manual actions are required.

   

5. Export the Report - You can export the report as a CSV file for documentation or further analysis by clicking Export Report.

   

6. Manual Review of Non-Success Entries - Any entries marked as non-success must be manually reviewed.

   Note: The tool does not attempt to resolve ambiguous or incomplete configurations. Developer intervention is required to ensure correctness.

Code registration for .ins and .drp files

Note: This is only for required for Uptime Maximizer customers.

During an upgrade, all INS scripts included in the delivery are executed. Since INS scripts contain DML statements, we must ensure that every DML in every INS file is EBR compliant, meaning they do not cause any visible changes to the online application while the upgrade is running in the background. This requires applying the correct editioning strategies to all code blocks across all INS files, which is a significant effort for developers.

To reduce this effort, code registration is introduced.

With this approach, existing code blocks in INS files that do not need to be executed repeatedly in every upgrade are tracked using the Code_Registration_SYS package. Each PL/SQL block in an INS file is wrapped with logic that checks whether it has already been registered.

• If it has not been registered - it is executed and then registered.

• If it is already registered - it is skipped.

The code registration task automates this wrapping process by scanning all .ins files in a given base directory, identifying PL/SQL blocks, and adding the necessary registration logic. In addition, each block is annotated with a comment:

--SAFE_FOR_ONLINE_DEPLOYMENT({current_date}, {username}, PRE_25R2_PATCH_REGISTERED)

Note: Developers are responsible for reviewing which blocks must still be executed in every upgrade, ensuring that appropriate editioning strategies are applied, and verifying that such blocks are correctly annotated with the safe deployment comment.

Sample INS File (Before)

---------------------------------------------------------------------
--
--  Filename      : test.ins
--
--  Module        : TEST
--
--  Date    Sign  History
--  ------  ----  ---------------------------------------------------
--  250901  abcdef  Created.
---------------------------------------------------------------------
SET SERVEROUT ON

PROMPT Test ins file inserting data

DECLARE
   date_ DATE := SYSDATE;
BEGIN
   DBMS_OUTPUT.PUT_LINE("Test ins file");
END;
/

Sample INS File (After)

---------------------------------------------------------------------
--
--  Filename      : test.ins
--
--  Module        : TEST
--
--  Date    Sign  History
--  ------  ----  ---------------------------------------------------
--  250901  abcdef  Created.
---------------------------------------------------------------------
SET SERVEROUT ON

PROMPT Test ins file inserting data
--SAFE_FOR_ONLINE_DEPLOYMENT(2025-09-01, abcdef, PRE_25R2_PATCH_REGISTERED)
BEGIN
   IF Code_Registration_SYS.Is_Not_Registered('TEST', 'test', '1', 'INS') THEN
      DBMS_OUTPUT.PUT_LINE('Deploying code block 1.');   
      DECLARE
         date_ DATE := SYSDATE;
      BEGIN
         DBMS_OUTPUT.PUT_LINE("Test ins file");
      END;
      Code_Registration_SYS.Register('TEST', 'test', '1', 'INS');
      COMMIT;
   ELSE
      DBMS_OUTPUT.PUT_LINE('Skipping Code block 1 because it has already been deployed.');
   END IF;
END;
/

Error Messages and Reasons

Error Message	Reason
Failed to process file: Invalid file path: Not within base directory (C:\\testFile.ins) | Requires manual handling	The file path is invalid. All files must reside within the specified base directory.
Failed to process file: Invalid file path: Unable to determine module name (C:\\testFile.ins) | Requires manual handling	The base directory must be either the workspace or a single module within it, as the module name is derived from the relative path.
Failed to process file: Failed to read file: C:\\ifs-applications\workspace\test\model\test\testFile.ins | Requires manual handling	The file could not be read, possibly due to permission issues or unexpected I/O errors.
Failed to process file: Invalid file path: C:\\ifs-applications\workspace\test\model\test\testFile.ins | Requires manual handling	The file does not exist or has been moved. Please verify the file location and rerun the tool.
Failed to process file: Cannot close PL/SQL block at line 10: No active block found | Requires manual handling	Invalid PL/SQL block state. No matching open block exists for the closing statement. Check for syntax errors.
Failed to process file: Cannot close PL/SQL block at line 10: Unexpected END statement without matching BEGIN/DECLARE | Requires manual handling	Invalid PL/SQL block state. The END statement does not have a corresponding BEGIN/DECLARE. Check for syntax errors
Failed to process file: Cannot close PL/SQL block at line 10: Current block type cannot be ended with END statement | Requires manual handling	Invalid PL/SQL block state. The block type does not support ending with an END statement. Check for syntax errors.
Failed to process file: Cannot close PL/SQL block: Reached end of file with open blocks | Requires manual handling	Invalid PL/SQL block state. One or more blocks remain unclosed at the end of the file. Check for syntax errors.
Partially processed file | 2 PL/SQL block(s) registered | 1 PL/SQL block(s) require manual handling	Some PL/SQL blocks in the file were already processed (annotated as safe for online deployment or code registered). Since it is unclear if omissions were intentional, partially processed files are skipped by the tool and must be reviewed manually.

The same code registration approach is applied to all .drp files as well.