How to create a component
A component is a set of rules which contain encapsulated functionality. Components hold an independent process which can be embedded in multiple applications; they do not depend upon one application's rules or functionality.
Enabling component functionality requires two wizards:
- the Create a Component wizard
- the Embed a Component wizard
After you run the Create a Component wizard, you must complete the component, and then run the Embed a Component wizard to embed the component into an application so it may be used.
This article describes how to build a component using the Create a Component wizard.
These tools are part of the optional Direct Capture of Objectives feature. The wizards are available to developers whose RuleSet list includes the Pega-AppDefinition RuleSet.
Before you begin
To understand what a component is, how it works, and why you might use it, see About Components. Verify that your functionality should be defined as a component (as opposed to a tool or a Shared RuleSet).
Design your component
Before you start the Create a Component wizard, you need to design your component. Determine what functionality you wish the component to accomplish, including:
- whether the component processing should be done by flow or by activity
- input parameters needed
- output properties
- names of clipboard pages which will be created or updated by the component
Include PegaRULES_DirectCapture application
In order to access the component wizard functionality, you must have the PegaRULES_DirectCapture application referenced in your Application rule. see How to Access and Use Direct Capture of Objectives Capabilities to verify that you have access to the appropriate RuleSets.
Using the wizard to create the component shell
1. From the File menu, choose New > Create a Component.
The Create Component form appears.
2. Enter your new component information:
the name for this component
the main class of the component
Component RuleSet Name
the RuleSet for this component
a description of the component’s purpose
3. In the Property to Embed in Application field, enter the name of the page property you will create in your application to embed this component.
Note that, as stated above, enabling component functionality is a two-step process. This wizard creates the component – the Embed wizard embeds it in the application. Therefore, this field is for informational purposes only – the application property will not be created until you are embedding the component in the application.
4. Click Next.
5. On the Entry Points and Outputs form, in the Component Entry Points section, choose whether your component’s main processing will be done with a flow or an activity.
a. In the Name field, enter the name for the flow or activity.
b. Enter one or more parameters for that flow or activity.
6. In the Component Outputs section, enter the Property Name, the Description, and the property Type for the output property that will hold the data which is the result of the component processing. (When you embed this component into an application, this data will be passed to that application.)
If you have multiple output properties, click the add row icon to add additional property fields.
7. Click Next.
8. On the Pages form, enter the names of any pages which are created or updated by your component. (This list will help other developers who are embedding your component in their application to prevent page name collisions.)
IMPORTANT: Try to name the pages you define in a component with unique and not-easily-duplicated names, to prevent having to rename application pages in case of duplication. For example, use names for your component pages like “CreditRatingComponentPage” or “OutlookAppointmentComponentPage”; do not use names like “MyPage”, “StepPage,” or “ComponentPage.” (You may not have a page in your application called “ComponentPage,” but if you have two components embedded in one application, there may also be a name duplication.)
9. Click Next.
10. On the Review form, verify that all the information for this component is correct, and then click Create.
11. The wizard creates the RuleSet, class, and other rules for the component. Once that is done, click Finish.
12. A status message appears:
“You have successfully created your component shell.
“Add the Component Ruleset RuleSetName to the component section of a development application so you can build and test your component. Use the AppExplorer Preferences to add RuleSetName as an additional RuleSet for your workpool if you want the component rules to appear in the explorer.”
Completing the component
IMPORTANT: This wizard has created the component, but does not add it into any applications. Before add functionality to your component shell, you must add your component RuleSet into a development application and restart your system, so you have access to edit and save rules for the component.
The component wizard will create the new RuleSet and Version and Class for the component, but it can only create the shell for some of the rules:
You must now add the appropriate shapes to your flow or steps to your activity to complete them, and create any additional rules which are needed for the desired functionality of this component (such as models, Whens, reports, harnesses, or other rules). For example, a component’s main activity might contain steps which:
- establish a SOAP connection to an external database and query it
- call another activity to run calculations
- run a report to display to the user
As part of writing the component, you might include some or all of the following types of rules:
These rules cannot be executed from an embedded page. If these rules are part of the component, they must be saved to the application’s class after the component has been embedded in that application. Therefore, if you have any of these rule types in your component, be sure to give them unique names so they will not conflict with any harnesses, SLAs, or reports already defined in the application.
You may create Declare Expressions rules as part of your component. Since a component is meant to be run from an embedded page in an application, and since that page may change from application to application (depending upon where you embed the component), any declarative expressions you create must be context-free.
As you build out your component, you may realize that you need to create other output properties, entry point flows or activities, or pages in addition to the ones created by the wizard. Once you have completed your component, record these additional new structures in the RuleSet Name or RuleSet Version rules, before embedding the component in an application, so they will be available for the Embed wizard.
To record additional component pages, open the component RuleSet Name rule. On the Category tab, add the additional pages under Component Clipboard Pages.
For additional flows or activities, open the component RuleSet Version rule. On the Interface tab, enter additional entry points under the Component Entry Points section.
Additional output properties can be entered in the Component Outputs section.
After you have created your component, you must embed it into an application to use the functionality. See How to embed a component into an application.