{"id":5681,"date":"2013-07-15T14:32:51","date_gmt":"2013-07-15T19:32:51","guid":{"rendered":"http:\/\/www.mrc-productivity.com\/docs\/?page_id=5681"},"modified":"2025-07-25T10:01:06","modified_gmt":"2025-07-25T15:01:06","slug":"external-objects","status":"publish","type":"ht_kb","link":"https:\/\/www.mrc-productivity.com\/docs\/knowledge-base\/external-objects","title":{"rendered":"External Objects"},"content":{"rendered":"\n<p class=\"wp-block-ht-blocks-messages wp-block-hb-message wp-block-hb-message--withicon is-style-info\"><em>Click <a href=\"https:\/\/www.mrc-productivity.com\/legacy\/m-power-build-process\/external-objects\">here<\/a> to access legacy documentation for this feature<\/em><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Overview<\/h2>\n\n\n\n<p>In m-Power, applications are built around database tables. These applications either:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Read and list database records<\/strong> (e.g., retrievals), or<\/li>\n\n\n\n<li><strong>Write or update database records<\/strong> using web forms (e.g., maintenances).<\/li>\n<\/ul>\n\n\n\n<p><strong>External objects<\/strong> extend these applications by allowing you to interact with <strong>external programs<\/strong>\u2014such as RPG, COBOL, CL, SQL stored procedures, or Java programs\u2014at various points in the app lifecycle. They serve as a bridge between m-Power application logic and your custom business logic.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">What can External Objects do?<\/h2>\n\n\n\n<p>At their core, external objects allow you to:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Trigger a program<\/strong> from within your m-Power app<\/li>\n\n\n\n<li><strong>Pass field values<\/strong> from the current record or web form into the external program<\/li>\n\n\n\n<li><strong>Receive return values<\/strong> from the program to populate or overwrite app field values<\/li>\n\n\n\n<li><strong>Perform validation<\/strong> and return custom error messages before the form is submitted<\/li>\n<\/ul>\n\n\n\n<p>This makes external objects incredibly useful for integrating legacy systems, enforcing complex business rules, or performing custom processing that isn&#8217;t feasible with built-in m-Power functionality.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Where Can You Use External Objects?<\/h2>\n\n\n\n<p>External objects can be integrated at different stages in an m-Power application:<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">In Retrievals and Reports<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Record-Level External Objects<\/strong>: Called for <strong>each record<\/strong> returned by the database query. This allows you to modify or enrich each record dynamically before it displays on the screen.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">In Maintainers (Web Forms)<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Before Display<\/strong>: Run a program <strong>before the form loads<\/strong> to prepopulate or initialize field values.<\/li>\n\n\n\n<li><strong>Before Add\/Update\/Delete<\/strong>: Call a program <strong>before the form submits<\/strong>, allowing you to:\n<ul class=\"wp-block-list\">\n<li>Validate user input<\/li>\n\n\n\n<li>Modify values before they\u2019re written to the database<\/li>\n\n\n\n<li>Cancel the submission and display a custom error message<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><strong>After Add\/Update\/Delete<\/strong>: Trigger a program <strong>after the data is written<\/strong>, typically used for post-processing tasks like sending confirmation emails, logging, or syncing data with other systems.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-ht-blocks-messages wp-block-hb-message wp-block-hb-message--withicon is-style-info\">View the full list of <strong><a href=\"https:\/\/www.mrc-productivity.com\/docs\/external-objects-udf\/external-object-locations\" target=\"_blank\" rel=\"noreferrer noopener\">locations<\/a><\/strong> where External Objects can be called <\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Types of External Objects<\/h2>\n\n\n\n<p>m-Power supports the following types of external programs:<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><tbody><tr><td class=\"has-text-align-left\" data-align=\"left\"><strong>RPG\/COBOL\/CL<\/strong><\/td><td class=\"has-text-align-left\" data-align=\"left\">Traditional IBM i programs using parameters.<\/td><\/tr><tr><td class=\"has-text-align-left\" data-align=\"left\"><strong>Java Class<\/strong><\/td><td class=\"has-text-align-left\" data-align=\"left\">Custom Java classes that implement specific logic.<\/td><\/tr><tr><td class=\"has-text-align-left\" data-align=\"left\"><strong>SQL Procedure<\/strong><\/td><td class=\"has-text-align-left\" data-align=\"left\">Stored procedures that run on the database server.<\/td><\/tr><tr><td class=\"has-text-align-left\" data-align=\"left\"><strong>URL-based API<\/strong><\/td><td class=\"has-text-align-left\" data-align=\"left\">Trigger external web services or REST APIs.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p>Each type has its own setup requirements, but they all follow the same general pattern: <strong>send in values, process logic, return results (if needed).<\/strong><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Management and Configuration<\/h2>\n\n\n\n<p>External objects are created and managed through the <strong>Admin > External Objects<\/strong> <strong>> Manage<\/strong> interface. From there, you can:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Define the object type and associated program name or class<\/li>\n\n\n\n<li>Set up parameters to map fields between your app and the external object (Optional)<\/li>\n<\/ul>\n\n\n\n<p>You can assign multiple external objects to a single application, each with its own timing and purpose.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Registering an External Object<\/h3>\n\n\n\n<p>When creating a new external object, you\u2019ll need to configure the following settings:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Object Name<\/strong>: A unique identifier for the external object. (Avoid using spaces.)<\/li>\n\n\n\n<li><strong>Description<\/strong>: A brief, user-friendly description of the object\u2019s purpose.<\/li>\n\n\n\n<li><strong>Object Type<\/strong>: Choose the appropriate type of external program.<\/li>\n<\/ul>\n\n\n\n<p>If using RPG\/CL\/COBOL or SQL:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Procedure Name<\/strong>: The name of the external program or stored procedure to call.<\/li>\n\n\n\n<li><strong>Procedure Schema<\/strong>: The library or schema where the program resides.<\/li>\n<\/ul>\n\n\n\n<p>If using Java:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Java Class Name<\/strong>: The full name of the Java class that contains the method.<\/li>\n\n\n\n<li><strong>Java Method Name<\/strong>: The method to be called, including any required arguments.<\/li>\n<\/ul>\n\n\n\n<figure class=\"wp-block-image size-large\"><a href=\"https:\/\/www.mrc-productivity.com\/docs\/vue-images\/registerEO.png.png\"><img decoding=\"async\" src=\"https:\/\/www.mrc-productivity.com\/docs\/vue-images\/registerEO.png\" alt=\"\"\/><\/a><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">Adding Parameters to an External Object<\/h3>\n\n\n\n<p>After saving the external object, click the <strong>View Parms<\/strong> button to define any parameters the program expects. <strong>Note:<\/strong> Parameters are optional. If your program does not send or receive any values, you can skip this step.<\/p>\n\n\n\n<p class=\"wp-block-ht-blocks-messages wp-block-hb-message wp-block-hb-message--withicon is-style-danger\">If parameters are used, they <strong>must be listed in the exact order<\/strong> they are defined in your external program.<\/p>\n\n\n\n<p><strong>Parameter Fields Explained:<\/strong><\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Object Name<\/strong>: Read-only. Indicates which external object this parameter belongs to.<\/li>\n\n\n\n<li><strong>Parameter Description<\/strong>: Enter a clear, user-friendly description of the parameter.<\/li>\n\n\n\n<li><strong>Parameter Name<\/strong>: Specify the name of the parameter (avoid using spaces).<\/li>\n\n\n\n<li><strong>Length \/ Decimals<\/strong>: Enter the parameter\u2019s total length and, if applicable, its number of decimal places. These must match the format defined in the external program.<\/li>\n\n\n\n<li><strong>Required Parm<\/strong>: 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.<\/li>\n\n\n\n<li><strong>Default Value<\/strong>: If the application may not pass a value for this parameter, you can define a default value here.<\/li>\n<\/ul>\n\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"https:\/\/www.mrc-productivity.com\/docs\/vue-images\/registerEOparm.png\" alt=\"\"\/><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">Associating an External Object to an Application<\/h3>\n\n\n\n<p>When you add an external object to an application, you\u2019ll be taken to a configuration screen where you define how and when the object should be used.<\/p>\n\n\n\n<p>Select the <strong>External Object<\/strong> and its <a href=\"https:\/\/www.mrc-productivity.com\/docs\/external-objects-udf\/external-object-locations\" target=\"_blank\" rel=\"noreferrer noopener\">execution location<\/a><strong> <\/strong>from the dropdown menus.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><a href=\"https:\/\/www.mrc-productivity.com\/docs\/vue-images\/external_objects1.png\"><img decoding=\"async\" src=\"https:\/\/www.mrc-productivity.com\/docs\/vue-images\/external_objects1.png\" alt=\"external_objects\"\/><\/a><\/figure>\n\n\n\n<p>Once selected, the <strong>Parameter Information<\/strong> section will display all parameters defined for the object.<\/p>\n\n\n\n<p>For each parameter, use the <strong>Map Field to Object Parameter<\/strong> dropdown to specify how the application should supply a value:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Select a Field<\/strong>: Map the parameter to an existing field in your application. This will pass the field\u2019s value to the external program.<\/li>\n\n\n\n<li><strong>Set a Default Value<\/strong>: Provide a static value that will always be passed to the parameter.<\/li>\n\n\n\n<li><strong>Select Nothing<\/strong>: Leave the field blank if the parameter is not required.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-ht-blocks-messages wp-block-hb-message wp-block-hb-message--withicon is-style-alert\">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.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><a href=\"https:\/\/www.mrc-productivity.com\/docs\/vue-images\/external_objects2.png\"><img decoding=\"async\" src=\"https:\/\/www.mrc-productivity.com\/docs\/vue-images\/externalObjApp.png\" alt=\"external_objects2\"\/><\/a><\/figure>\n\n\n\n<p>Once finished, click <strong>Save External Object<\/strong>. <\/p>\n\n\n\n<p>If you are recompiling an existing application, you can leave the <strong>Overwrite HTML<\/strong> option unchecked to preserve any custom HTML changes.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">External Object Resources<\/h2>\n\n\n\n<p>For advanced information about external objects, please see:<\/p>\n\n\n\n<p><a href=\"https:\/\/www.mrc-productivity.com\/docs\/external-objects-udf\/sample-external-object-rpg\">Sample RPG External Object<\/a><br><a href=\"https:\/\/www.mrc-productivity.com\/docs\/external-objects-udf\/sample-external-object-java\">Sample Java External Object<br><\/a><a href=\"https:\/\/www.mrc-productivity.com\/docs\/external-objects-udf\/sample-external-object-sql\">Sample SQL External Object<br><\/a><a href=\"https:\/\/www.mrc-productivity.com\/docs\/form-validation-techniques\/validating-via-an-rpg-external-object\">Validating Via a RPG External Object<br><\/a><a href=\"https:\/\/www.mrc-productivity.com\/docs\/form-validation-techniques\/validating-via-a-java-external-object\">Validating Via a Java External Object<br><\/a><a href=\"https:\/\/www.mrc-productivity.com\/docs\/form-validation-techniques\/validating-via-an-sql-external-object\">Validating Via a SQL External Object<br><\/a><a href=\"https:\/\/www.mrc-productivity.com\/docs\/external-objects-udf\/return-data-external-object\">Return Data External Object<br><\/a><a href=\"https:\/\/www.mrc-productivity.com\/docs\/external-objects-udf\/regular-expression-external-object\">Regular Expression External Object<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Overview In m-Power, applications are built around database tables. These applications either: External objects extend these applications by allowing you to interact with external programs\u2014such as RPG, COBOL, CL, SQL stored procedures, or Java programs\u2014at various points in the app lifecycle. They serve as a bridge between m-Power application logic&#8230;<\/p>\n","protected":false},"author":1,"comment_status":"closed","ping_status":"closed","template":"","format":"standard","meta":{"footnotes":""},"ht-kb-category":[248],"ht-kb-tag":[],"class_list":["post-5681","ht_kb","type-ht_kb","status-publish","format-standard","hentry","ht_kb_category-build-process"],"_links":{"self":[{"href":"https:\/\/www.mrc-productivity.com\/docs\/wp-json\/wp\/v2\/ht-kb\/5681","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.mrc-productivity.com\/docs\/wp-json\/wp\/v2\/ht-kb"}],"about":[{"href":"https:\/\/www.mrc-productivity.com\/docs\/wp-json\/wp\/v2\/types\/ht_kb"}],"author":[{"embeddable":true,"href":"https:\/\/www.mrc-productivity.com\/docs\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.mrc-productivity.com\/docs\/wp-json\/wp\/v2\/comments?post=5681"}],"version-history":[{"count":34,"href":"https:\/\/www.mrc-productivity.com\/docs\/wp-json\/wp\/v2\/ht-kb\/5681\/revisions"}],"predecessor-version":[{"id":14636,"href":"https:\/\/www.mrc-productivity.com\/docs\/wp-json\/wp\/v2\/ht-kb\/5681\/revisions\/14636"}],"wp:attachment":[{"href":"https:\/\/www.mrc-productivity.com\/docs\/wp-json\/wp\/v2\/media?parent=5681"}],"wp:term":[{"taxonomy":"ht_kb_category","embeddable":true,"href":"https:\/\/www.mrc-productivity.com\/docs\/wp-json\/wp\/v2\/ht-kb-category?post=5681"},{"taxonomy":"ht_kb_tag","embeddable":true,"href":"https:\/\/www.mrc-productivity.com\/docs\/wp-json\/wp\/v2\/ht-kb-tag?post=5681"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}