How to embed a component into an application
Summary
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 embed an existing component into an application using the Embed 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.
Suggested Approach
Before you begin
To understand what a component is and how it works, see About Components.
Before you start the Embed a Component wizard, you must have created the component (see How to create a component). You must also have an application to embed the component into.
Using the wizard to embed the component
1. Verify that the application into which you wish to embed your component is the application open on your desktop. If it is not, open that application.
2. From the File menu, choose New > Embed a Component.
The Embed Component form appears.
3. From the dropdown lists, select the RuleSet and version of the component you wish to embed in the application.
Once these have been selected, the application fields appear:
4. Enter the Embed Component Into information for the application where the component is being embedded:
Field | Description |
|---|---|
Application RuleSet | The RuleSet in this application into which you wish to embed the component. This will be the RuleSet in which the application properties and the declarative expression (specified below) will be defined. |
Application RuleSet Version | The version of the application RuleSet. This RuleSet Version must be unlocked so that the the application properties and the declarative expressions can be saved. |
Application Class to Embed Into | The class where you wish to call the component functionality from (your work object class). Defaults to the current workpool class for this application. This will be the class on which the application properties and the declarative expression (specified below) will be defined. |
Application Property to Embed Into | The page property where the component class will be embedded. Defaults to the value entered into the “Property to Embed in Application” in the Create a Component wizard. |
5. The Map Component Outputs section of this form maps the component output property (or properties) to a property (or properties) defined in the application. The application properties listed in the Map to Application Property field will be defined on the Application Class to Embed Into, and then Declare Expressions will be created (also on that class) to provide the mapping.
Enter your output property or properties in the Component Property field, and enter names for the application properties they will be mapped to in the Map to Application Property field.
NOTE: Although you could map to existing application properties, in most cases you should enter new property names, and the wizard will generate the new properties.
6. Click Next.
7. The Identify Manual Items form displays any harnesses, SLAs, or reports which are in the Component. Such rules will not run on embedded pages, so they must be manually copied into the application class.
For each harness, SLA, or report entered on this page, click on the entry in the table to open the rule. Save the rule into the appropriate application class and RuleSet, and then close both rules.
8. You must also verify that no pages in your application which are created or updated have the names used by the component pages, to prevent conflicts. Use this list to compare with the pages that are used by your application.
9. Click Next.
10. On the Review form, verify that all the information for embedding this component is correct, and then click Create.
11. The wizard updates the Application rule to include the component RuleSet, and create the specified properties and Expressions. Once that is done, click Finish.
12. A status message appears:
“You have successfully embedded RuleSetName into your application.
“The next step is to update your application to call the component functionality by using the entry points.”
A list of the entry points is displayed.
Click Close.
Updating the application
Once the component is embedded into your application, you must update your application with any required manual changes, and then call the component functionality.
If there were page name collisions, rename the pages that were created in your application so they are unique. (Change the names of the pages in the application rather than the component. The component – by definition – is designed to be part of multiple applications; if an updated component version is released, you don’t want to have to re-change all the page names to something different for each application where it is embedded.)
Edit your application to call the component functionality from the embedded page. For a component activity, you can just call the entry-point activity, using the application property where the component is embedded as the step page.
Flows allow you to call sub-flows, and to specify that these sub-flows are on an embedded page. In the Spinoff Properties box of a subflow shape, enter the following information for the embedded component:
- Define Flow – “On Embedded Page”
- Page Property – the application property where the component is embedded
- Class – the component class
- Flow Rule – the name of the entry-point flow rule
(Also enter any other information related to your subflow, such as Audit Notes.)
