Skip to main content

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Intuitive record creation and specialization

Suggest edit Updated on September 10, 2021


Adding records to your application is now streamlined for a faster, more intuitive experience. The familiar “New” and “Save As” forms have been revamped to target the creation of a record into a specific layer in your application stack. Fields and values smartly scope as you interact with the form, while a new defaulting strategy helps you quickly choose the right context for your rule. 

Read this article to learn more about the different ways records are created, including:

What's changed in Pega 7?

While record creation is not a new feature to Pega 7, a number of modifications and enhancements have been made to simplify the experience.

Improved access to the +Create menu

Additional access points to the +Create menu have been exposed throughout the Designer Studio. 

The Top Level menu in each of the explorers contains the full +Create menu, with options to create records of any category or type. The Records and Application explorers provide additional right-click access to a scoped +Create menu, which only displays record types applicable to the selected category.

The form header for all records and instance lists includes the full +Create menu. Single-click +Create to create a new record of the same type as the one in focus, or expand the menu to make a selection from the full set of options.

Three distinct actions

There are different use cases for creating a rule or data instance. There are times you want to create a record from scratch. When copying an existing record, you may want to change all, some, or none of its key parts. When circumstancing a rule, you may want to change the context in addition to defining a set of circumstance definitions. All of these actions result in the creation of a new record yet require different types of information.

As a result, the actions area of the form header has been restructured to make a clear distinction between three types of actions. Choose the action that matches your use case and only the options that are relevant will be displayed:

Interactive forms

The fields and available options on the Create, Save As, and Specialization forms respond to you real-time as you make selections. Menu options filter to display only those values that are visible to your specified application layer. Fields and controls disable when they become incompatible with any of your current selections. Advanced options are only exposed on the form when you explicitly enable them. Complexity and confusion have been eliminated, so you can focus on creating your record correctly the first time.

Below is a brief overview of the common form structure. For more details on all fields and their purpose, see Using the create and save as form and Using the specialization forms.

  • Form header - Use the buttons in this area to submit the form and create your record. The icon is available for help topics specific to the record type you want to create.

  • Record configuration - Use this area of the form to name your record and define its key parts. Options to define circumstance definitions appear here when using the Specialize by circumstance action.

  • Record context - Use this area of the form to define your record’s position in the ruleset stack and how it may be reused or accessed in the class hierarchy. 

  • Project Management - Use this area of the form to link your development changes to items in your PMF worklist. This section is only available when your application has been integrated with a PMF instance.

Using the Create and Save As forms

The "Create" and "Save As" forms are very similar in presentation and functionality. All fields are interactive and open for edit (unless the record type has name restrictions). The "Save As" form provides all of the fields and features as the "Create" form, with the exception of the additional creation options section, which is only available for creating specific record types.

Record configuration

Use the fields in the record configuration area of the form to name your record and define its key parts.

Short description

Enter a sentence (with spaces) that describes the purpose of the record.

It is a best practice to enter no more than 30 characters; the limit is 64.

Behind the scenes, the value you enter here is mapped to the pyLabel property of the record which appears in the form header, Recent explorer, and other reports and menus in the Designer Studio.


The Identifier field represents the name key part of your record. By default, this field is set to "To be determined". 

It then updates to a read-only value based on the sentence entered in the short description field; spaces and special characters are removed.

To manually set the Identifier to a value that is different from the short description, click the Edit link next to the Identifier. Update the field in the overlay and click OK to save your changes.

Once you have explicitly set the Identifier in this manner, it will no longer auto-populate if a new short description is provided.

When using the Save As action for a record type that has name restrictions (like Case), the Identifier field may be read-only.

Key parts

The remaining fields in the record configuration area of the form represent additional key parts for your record. The number of key parts, types, and restrictions vary by record type.

Generally, start each key part with a letter and use only letters, digits, and the dash character. For key part guidance that is specific to the type of record you want to create, click the help icon on the "Create" and "Save As" forms.

Additional creation options

Previously referred to as "Quick Create," additional configuration options define a starting point for your record. This speeds up creation time and allows you to directly create the record without having to first open and explicitly Save it.

Click the View additional configuration options link to enable all other configuration options supported by this record type on the form:

In the example below, a When rule is created that has a When Expression as its additional configuration option. Specifying a string expression here automatically sets the when condition that evaluates each time the new record is called. 

To clear any selections you made to the additional configuration fields, click the Remove additional configuration options link:

The available actions in the form header depend on the selections you have made on the form. The Create and open button is always available; click to create the record and open its form so you can make additional changes. The Create and close button appears when you have specified additional creation options; click to create the record, close the form and return you to your previous context.

Like key parts, additional configuration options vary by record type. Click the help icon on the Create form for guidance on how each configuration option affects the newly created record. 

Record context

Use the record context area of the form to specify where the record will reside in your application ruleset stack and how it may be reused in the class hierarchy. Since the majority of fields are interrelated, it may be helpful to review the following example use case before delving into the details for each option on the form:

Development branch

Select a branch name from the list to create the record in a branched version of the ruleset specified in the Add to ruleset field. Branches from all levels of your application stack appear in the list of development branches, regardless of the application layer you have specified:

While branching is optional, you should note how choosing a branch name vs. [No branch] affects the available options in the Add to ruleset and version fields:

The branched ruleset version will automatically be created (if not already) and added to your Development branch when the Create or Save As form is submitted.

Choose app layer

Define how your record will be reused by selecting the name of an application in your stack. Specifying an application name helps you define a record's full context by automatically filtering the list of available options in the Apply to and Add to ruleset fields.

Only application layers with access to the selected Development branch are enabled for selection. To choose an application name that is currently disabled (other than the base PegaRULES application), you first need to set the Development branch to the [No branch] option.

In the example above, the "Production Rulesets" option is available. This appears as the top most radio button option in the stack if your current Access Group has production rulesets defined. Choosing this option will restrict values the Add to ruleset field only.

Apply to

Select a class to which this record applies. By default, this list is populated by the cases and data object types accessible by your chosen app layer

To select a class name that is not a case or data object type, click the View all link:

Generally, choose an Apply to class that is the most specific (i.e. the lowest in the class hierarchy that serves the needs of your application). For example, choose MyCo-LoanDiv-MortgageApplication rather than MyCo-LoanDiv- as the Apply to class for a new flow or property, unless you are certain that the record is applicable to all the objects in every class derived from MyCo-LoanDiv-.

Add to ruleset

​Select the name of a ruleset to contain the record. If the Development branch is set to [No branch], you must also specify a version for the specified ruleset name.

The ruleset name list is populated by the rulesets available to your selected app layer and additionally filtered by any restrictions set by the selected Apply to class. The ruleset version list is populated by all unlocked versions. 

Project Management

Use the fields in this area of the form to associate your development actions with items assigned to you in your PMF worklist. The Project Management section in its entirety is only displayed on the "Create" and "Save As" forms when the following criteria are met:

  • System > Settings > Project Management landing page has valid PMF connection details
  • Application record has Enable Project Management checkbox selected
  • Operator preferences specifies a valid PMF User ID

No significant enhancements to PMF integration have been introduced in Pega 7. For more details on the individual fields and options, refer to the PRPC Help system (online version available on the PDN).

Using the specialization forms

Use one of the specialization forms when you want to keep the same name as an existing record, but modify the context or add a circumstance that will affect rule resolution.

Specialize by class or ruleset

The Specialize by class or ruleset form is ideal when you want to copy an existing record and only change parts of its context: apply to class, ruleset name, or ruleset version. Like the "Create" and "Save As" forms, you are prompted for the new record’s configuration and context.

The identifier is the only field on the form that is restricted (read-only), however, you may provide an alternative short description:

To view details about the original record’s context and configuration, hover over the short description in the form header:


Once you have verified your selections for the new context, submit the form to create the record.

Original record details are also available on the "Specialize by circumstance" and "Save As" forms.

Specialize by circumstance

The "Specialize by circumstance" form is used when you want to extend a base version of a rule by defining one or more special cases (or circumstances) for it. Multivariate, property and date range circumstanced versions of rules are supported.

Like the "Create" and "Save As" forms, you are prompted for the new record’s configuration and context with the following limitations:

  • The identifier is restricted (read-only)
  • The apply to class may only be changed to a descendant of the original value

Use the fields and options outlined below to define the circumstance(s) for your record.

Circumstance by template

Choose the Template radio button when you plan on creating a record that is circumstanced by more than one property value (also referred to as multivariate circumstancing). This option requires you to have at least one template rule created ahead of time that is visible to the selected application layer.

Next, select the name of a template rule. Templates specify which combinations of properties may be evaluated by corresponding circumstance definition rules. The list of templates is scoped based on the application layer and apply to class you have specified.

Lastly, select a definition rule that matches your special case (or circumstance). This definition contains an expression that will be evaluated during rule resolution to determine whether or not your circumstanced version is selected.

Like templates, you must have at least one definition rule created ahead of time that is visible to the selected application layer; it must also map to the selected template rule.

For more examples on using circumstance definitions and templates, see How to create a rule with multiple circumstance properties.

Circumstance by property

Choose the Property radio button when you plan on creating a record that is circumstanced by a single property value, date property value, date range, or any combination of the three. 

Select the name of a property to evaluate and its expected value in the form of string in quotations. This is the string that will be evaluated during rule resolution to determine whether or not your circumstanced version is selected.

Leave these fields blank if you only plan on specifying a date property circumstance with an optional date range.

Select the name of a date property to evaluate and its expected date value by using the calendar control. This is the value that will be evaluated during rule resolution to determine whether or not your circumstanced version is selected.

Leave these fields blank if you only plan on specifying a property circumstance with an optional date range.

Use the Add a date range link to define a date range value in conjunction with a property or date property circumstance. Otherwise, it is recommended that you use the Date range only option below. The Remove date range link is available if you decide your circumstance definition no longer requires a date range.

ALL definitions specified in this area of the form must evaluate to true for your circumstanced version to be selected during rule resolution.

Circumstance by date range

Choose the Date range only radio button when you plan on creating a record that is circumstanced by a range of time (evaluated at time of rule execution). 

Select a start and end date by using the calendar controls. This is the window of time that will be evaluated against the current system time to determine whether or not your circumstanced version is selected.

Once you have verified your selections for the circumstance, submit the form to create the record.


Pega Platform 7.1.1 - 8.3.1 System Architect Lead System Architect Business Architect UX Developer Project Manager System/Cloud Ops Administrator Low-Code App Development Financial Services Healthcare Insurance Media and Advertising Government Life Sciences Utilities
Did you find this content helpful? YesNo

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us