Click here to access legacy documentation for this feature
Overview
In m-Power, applications are built around database tables. These applications either:
- Read and list database records (e.g., retrievals), or
- Write or update database records using web forms (e.g., maintenances).
External objects extend these applications by allowing you to interact with external programs—such as RPG, COBOL, CL, SQL stored procedures, or Java programs—at various points in the app lifecycle. They serve as a bridge between m-Power application logic and your custom business logic.
What can External Objects do?
At their core, external objects allow you to:
- Trigger a program from within your m-Power app
- Pass field values from the current record or web form into the external program
- Receive return values from the program to populate or overwrite app field values
- Perform validation and return custom error messages before the form is submitted
This makes external objects incredibly useful for integrating legacy systems, enforcing complex business rules, or performing custom processing that isn’t feasible with built-in m-Power functionality.
Where Can You Use External Objects?
External objects can be integrated at different stages in an m-Power application:
In Retrievals and Reports
- Record-Level External Objects: Called for each record returned by the database query. This allows you to modify or enrich each record dynamically before it displays on the screen.
In Maintainers (Web Forms)
- Before Display: Run a program before the form loads to prepopulate or initialize field values.
- Before Add/Update/Delete: Call a program before the form submits, allowing you to:
- Validate user input
- Modify values before they’re written to the database
- Cancel the submission and display a custom error message
- After Add/Update/Delete: Trigger a program after the data is written, typically used for post-processing tasks like sending confirmation emails, logging, or syncing data with other systems.
View the full list of locations where External Objects can be called
Types of External Objects
m-Power supports the following types of external programs:
| RPG/COBOL/CL | Traditional IBM i programs using parameters. |
| Java Class | Custom Java classes that implement specific logic. |
| SQL Procedure | Stored procedures that run on the database server. |
| URL-based API | Trigger external web services or REST APIs. |
Each type has its own setup requirements, but they all follow the same general pattern: send in values, process logic, return results (if needed).
Management and Configuration
External objects are created and managed through the Admin > External Objects > Manage interface. From there, you can:
- Define the object type and associated program name or class
- Set up parameters to map fields between your app and the external object (Optional)
You can assign multiple external objects to a single application, each with its own timing and purpose.
Registering an External Object
When creating a new external object, you’ll need to configure the following settings:
- Object Name: A unique identifier for the external object. (Avoid using spaces.)
- Description: A brief, user-friendly description of the object’s purpose.
- Object Type: Choose the appropriate type of external program.
If using RPG/CL/COBOL or SQL:
- Procedure Name: The name of the external program or stored procedure to call.
- Procedure Schema: The library or schema where the program resides.
If using Java:
- Java Class Name: The full name of the Java class that contains the method.
- Java Method Name: The method to be called, including any required arguments.
Adding Parameters to an External Object
After saving the external object, click the View Parms button to define any parameters the program expects. Note: Parameters are optional. If your program does not send or receive any values, you can skip this step.
If parameters are used, they must be listed in the exact order they are defined in your external program.
Parameter Fields Explained:
- Object Name: Read-only. Indicates which external object this parameter belongs to.
- Parameter Description: Enter a clear, user-friendly description of the parameter.
- Parameter Name: Specify the name of the parameter (avoid using spaces).
- Length / Decimals: Enter the parameter’s total length and, if applicable, its number of decimal places. These must match the format defined in the external program.
- Required Parm: Check this box if the parameter is required for the program to function. If enabled, the object cannot be added to an application unless a corresponding app field is mapped to this parameter.
- Default Value: If the application may not pass a value for this parameter, you can define a default value here.
Associating an External Object to an Application
When you add an external object to an application, you’ll be taken to a configuration screen where you define how and when the object should be used.
Select the External Object and its execution location from the dropdown menus.
Once selected, the Parameter Information section will display all parameters defined for the object.
For each parameter, use the Map Field to Object Parameter dropdown to specify how the application should supply a value:
- Select a Field: Map the parameter to an existing field in your application. This will pass the field’s value to the external program.
- Set a Default Value: Provide a static value that will always be passed to the parameter.
- Select Nothing: Leave the field blank if the parameter is not required.
Required parameters must be mapped to either a field or a default value. The object cannot be saved to the application unless all required parameters are properly mapped.
Once finished, click Save External Object.
If you are recompiling an existing application, you can leave the Overwrite HTML option unchecked to preserve any custom HTML changes.
External Object Resources
For advanced information about external objects, please see:
Sample RPG External Object
Sample Java External Object
Sample SQL External Object
Validating Via a RPG External Object
Validating Via a Java External Object
Validating Via a SQL External Object
Return Data External Object
Regular Expression External Object