Discussion

1593
Views
steik Member since 2013 1 post
PEGA
Posted: 1 year ago
Last activity: 1 year 11 months ago

New Application API

Owners

Planet express scrum team

Change log

7.1.8:

  • Core set of functionality introduced - allows for creation of "bare-bones" application

7.2.2:

  • Ability to clone case types / associate data type links to new application
  • Ability to more directly configure application settings (class layer naming, application skin, application structure)
  • Cloning of access role names / role objects for security in new application
  • Proper error handling for all preparation apis to check that required parameters are actually passed, and if not, give the user an informative error instead of previously not reporting any until generation time, or reporting generic CannotBeBlank error.
  • Improved performance of preparation apis to utilize faster existing rule checking, and no longer perform unnecessary Obj-Opens

7.3:

  • Added support to advanced settings to skip cloning of access roles during application creation.

7.3.1:

  • Added support in class preparation to always prepare a database table for the class

7.4:

  • Removed UIKitExpress support for new applications
  • Added support to create product rule for new applications
  • Removed the generation of new operators for new applications
    • Removed the generation of demo operators for new applications building on a template
    • Removed generation of default operators for new applications building on PRPC
    • Removed the generation of new operators if present in the standard queues
    • If any of the queues have new operators (pzInsKey == ""), we add a log-message indicating new operators cannot be generated
    • If any of the queues have existing operators(pzInsKey !=""), we save them

8.1:

  • Preparing and generating UI Pages class
  • Changes in App preparation to update the application with UI pages class

High-level overview

The new application API follows the following approach:

  1. Prepare objects for generation based on inputs and add them to generation queues
  2. Call extension points that allow for
    1. augmentation of objects in the generation queues
    2. addition of objects to a generic generation queue or to the specific queues
  3. Save objects in the generation queue.

How to clone case types / create data links for new application (new in 7.2.2)

  1. Two existing datapages 'D_pxGetClonableCaseTypesOfApp and D_pxDataTypesForApplication exist for your use and each contain a list of case types / data types respectively that are stored in individual pxResults pages.
    1. Note - You may implement your own list of case types / data types if desired. However, the requirements in order for the API to function properly are that you populate each pxResult page with the following fields at a minimum:
    2. CaseType - Properties required if using own sourceDataType - Properties required if using own source

      Case type specific properties:

      pyClassName - [Required] - class the case type is being cloned from

      pyLabel - [Required] - label for the case type

      pyDescription - [Optional] - description for the case type

      pyBaseClass - [Optional] - if this value is present, it will be used as the desired class group for the new case type class

      pyClassNameTemp - [Optional] - if this value is present, it will be used as the desired class for the new case type

      Properties for cases & data tab:

      pyShowInNewWorkMenu - [Required] - true or false (set on the cases & data tab for the application on whether to show in the create menu)

      pyWorkPrefix - [Optional] - if this value is present, it will be used as the work prefix under cases & data tab for the application

      pyWorkTypeName - [Optional] - if this value is present, it will be used as the work type name under cases & data tab for the application

      pyWorkIcon - [Optional] - if this value is present, it will be used as the work icon under cases & data tab for the application

      pyMetadataKey - class of the data type

      pyLabel - used for UI purposes for selection (not required)

      pyDescription - used for UI purposes for selection (not required)

  2. Once you have loaded the appropriate info for cases / data, you can get the reference to the page containing the list of resutls via @Utilities.pxGetStepPageReference() and pass these values along to pxSetCasesAndData API.
  3. pxSetCasesAndData will instantiate two embedded properties pyCaseTypesToClone and pyDataTypesToLink which are then processed later as part of pxPrepareApplicationObjects when calling pxPrepareCasesAndData and passed along to pxCloneCaseTypes / pxLinkDataTypes.
  4. Call pxBuildApplication

How to set advanced settings for new application (new in 7.2.2)

  1. Prior to calling pxBuildApplication, you can utilize pxPrepareAdvancedSettings which supports additional configuration options not supported out of the box
    1. Any values supplied will be stored and processed later as part of pxSetBasicDefaults to override basic default settings
  2. Call pxBuildApplication NOTE - you must be calling the Data-Application-Configuration version. Advanced settings will not be set or consumed if calling the @baseclass implementation.

How to set up your own implementation

In order to utilize the set of APIs defined on Data-Application-Configuration provided in a different manner than the defaults, a specific order needs to be followed:

  1. Start by setting up the preparation page (Follow pxBuildApplication as a guideline)
  2. Next, setup the generation page (pxSetupGenerator)
  3. Next, set the basic top level properties needed for the preparation APIs by calling pxSetBasicDefaults
    1. Note - If you have additional advanced configuration in mind, you can call pxPrepareAdvancedSettings to further configure your application
  4. Next, if you have case types you would like to clone, or data types to link, you can call pxSetCasesAndData to instantiate the pages necessary for preparing case types / data links you wish to be created later.
  5. Next, follow the same structure as pxPrepareApplicationObjects for a general idea of the order required to create objects. This is necessary as certain rules have dependencies on others.
  6. Add a call to framework extensions using the activity, pzPrepareFrameworkAssetsForGeneration if you want your implementation to be extendable.
    1. Use the extension points to augment assets already in the generation queues
    2. Use the extension points add assets for generation.
  7. When satisfied with the objects desired for your new application, call pxGenerateApplication
  8. You’re done! Plug in your activity where desired and give it a run.

Getting started

The following activities are responsible for setting up and calling defaulting, preparation, framework assets and generation activities. These are examples to look at as a user if trying to implement an alternative solution to what is offered in this basic scenario.

pxBuildApplication - @baseclass

  • Parameters:
    • AppName – the application name [Required]
    • AppLabel – the application label [Optional]
    • Description – the application description [Optional]
    • BuiltOnApp – the built on application [Optional]
    • OrgName – the organization name [Required]
    • OrgLabel – the organization label [Optional]
    • DivName - the division name [Optional]
    • DivLabel - the division label [Optional] - new in 7.2.2
    • UnitName - the unit name [Optional]
    • UnitLabel - the unit label [Optional] - new in 7.2.2
    • TestOpsPassword – test operators’ password [Optional]
    • WorkGroupManager – the workgroup manager [Required]
    • ConfigurationClass - a class that inherits from Data-Application-Configuration [Optional]
  • Purpose:
    • Determines the correct context to run in based on the ConfigurationClass parameter passed. If left blank, it is defaulted to Data-Application-Configuration. If provided, the class must inherit from Data-Application-Configuration. A new page of the ConfigurationClass will be created.
  • Activities referenced:
    • pxBuildApplication – Data-Application-Configuration

pxBuildApplication – Data-Application-Configuration

  • Parameters:
    • AppName – the application name [Required]
    • AppLabel – the application label [Optional]
    • Description – the application description [Optional]
    • BuiltOnApp – the built on application [Optional]
    • OrgName – the organization name [Required]
    • OrgLabel – the organization label [Optional]
    • DivName - the division name [Optional]
    • DivLabel - the division label [Optional] - new in 7.2.2
    • UnitName - the unit name [Optional]
    • UnitLabel - the unit label [Optional] - new in 7.2.2
    • TestOpsPassword – test operators’ password [Optional]
    • WorkGroupManager – the workgroup manager [Required]
    • AdminUserId - id of the admin user [Optional]
    • AdminUserName - name of the admin user [Optional]
    • AdminUserEmail - email of the admin user [Optional]
  • Purpose:
    • Set basic defaults, and determine whether a context switch is required for application creation.
  • Activities referenced:
    • pxSetBasicDefaults – sets basic defaults on top level to be used later on
    • pzBuildApplicationInner – sets up generation page, prepares application objects, prepares framework assets

pxBuildApplication – Data-Application-Configuration-Tenant

  • Parameters:
    • AppName – the application name [Required]
    • AppLabel – the application label [Optional]
    • Description – the application description [Optional]
    • BuiltOnApp – the built on application [Optional]
    • OrgName – the organization name [Required]
    • OrgLabel – the organization label [Optional]
    • DivName - the division name [Optional]
    • DivLabel - the division label [Optional] - new in 7.2.2
    • UnitName - the unit name [Optional]
    • UnitLabel - the unit label [Optional] - new in 7.2.2
    • TestOpsPassword – test operators’ password [Optional]
    • WorkGroupManager – the workgroup manager [Required]
    • AdminUserId - id of the admin user [Optional]
    • AdminUserName - name of the admin user [Optional]
    • AdminUserEmail - email of the admin user [Optional]
    • AdminUserExists - does the admin user already exist? [Optional]
  • Purpose:
    • Set basic defaults, and determine whether a context switch is required for application creation when building a tenant application
  • Activities referenced:
    • pxSetBasicDefaults – sets basic defaults on top level to be used later on
    • pzBuildApplicationInner – sets up generation page, prepares framework assets

pzBuildApplicationInner – Data-Application-Configuration

  • Purpose:
    • Sets up generation page, prepares framework assets and runs through generation of objects which have been prepared
  • Activities referenced:
    • pxSetupGenerator – sets up the generation page
    • pxPrepareApplicationObjects – prepares application environment & all needed objects
    • pzPrepareSampleAssets - prepares sample assets for an application (can be overrided at specific class levels)
    • pzPrepareFrameworkAssetsForGeneration – prepares framework assets for generation
    • pxGenerateApplication – generate the application& all objects that were prepared

pxSetupGenerator – Data-Application-Configuration

  • Purpose:
    • Create the generation page (pyApplicationGenerator – Data-Application-Generation)

Setting top level properties

The following activities are responsible for setting a list of top level properties for use later during the preparation of objects to be generated.

pxSetBasicDefaults – Data-Application-Configuration

  • Parameters:
    • AppName – the identifier for the application [Required]
    • AppLabel – the label for the application [Optional]
    • Description – the description for the application [Optional]
    • OrgName – the organization identifier [Required]
    • OrgLabel – the label for the organization [Optional]
    • DivName - the division name [Optional]
    • DivLabel - the division label [Optional] - new in 7.2.2
    • UnitName - the unit name [Optional]
    • UnitLabel - the unit label [Optional] - new in 7.2.2
    • BuiltOnApp – the built on application name [Optional]
    • BuiltOnAppVersion – the version of the built on application [Optional]
  • Purpose:
    • Set defaults if Optional parameters were left blank. If the user provided any advanced configuration settings through pxPrepareAdvancedSettings, then they are applied here. Validates that the defaults/advanced settings are ‘good’ and that application preparation can continue. Set the organization, division and unit information. Set application specific information and setup the default class structure as well as ruleset names.
  • Activities referenced:
    • pzValidateBasicDefaults – checks that all top level properties are set
    • pxSetOrgInfo – sets organization, division and unit name
    • pxSetDefaultAppInfo – sets up application information on specified page
    • pxSetClassStructure – sets the default class structure
    • pxSetRuleSetNames – sets the default ruleset names

pxSetOrgInfo – Data-Application-Configuration

  • Parameters:
    • OrgName – the name of the organization [Required]
    • OrgLabel – the label for the organization [Optional]
    • DivName – the name of the division [Required]
    • DivLabel - the label of the division [Optional] - new in 7.2.2
    • UnitName – the name of the organizational unit [Required]
    • UnitLabel - the label of the organizational unit - new in 7.2.2
  • Purpose:
    • Stores the organization, division and unit names for later use in preparation
  • Properties set:
    • pyOrganizationName – store the organization name
    • pyOrganizationLabel – store organization label
    • pyCreateDivClassLayer – store whether to create division class layer? ->
    • pyDivisionName – store the division name
    • pyDivisionLabel - store the division label - new in 7.2.2
    • pyCreateUnitClassLayer – store whether to create unit class layer?
    • pyUnitName – store the unit name
    • pyUnitLabel - store the unit label - new in 7.2.2

pxSetDefaultAppInfo – Data-Application-Configuration

  • Parameters:
    • ApplicationPage – the application page to work on [Required]
    • AppName – the name of the application [Required]
    • AppLabel – the description of the application [Optional]
    • ApplicationSkin - the skin for the application to use [Optional]
    • BuiltOnApp – the built on application [Required]
    • BuiltOnAppVersion – the built on application version [Required]
  • Purpose:
    • Sets pertinent information about the application for use later in preparation. Supports multiple application pages to allow for Implementation/Framework usecase.
  • Properties set:
    • pyApplicationName – the application name
    • pyLabel – the application label
    • pyDescription – the application description
    • pyDependsOnName – the built on application
    • pyDependsOnVersion – the built on application version
    • pyUsedAs - Built-on choice for AE
    • pyProjectMethodology - Project methodology
    • pySkinType - the application skin

pxSetClassStructure – Data-Application-Configuration

  • Parameters:
    • OrgLayer – the org layer for your class [Required]
    • CreatingImplementation - creating an implementation application? [Required]
    • AppLayer – the implementation layer [Optional]
    • DivLayer – the division layer [Optional]
    • UnitLayer – the unit layer [Optional]
    • ImplementationClassGroup – the implementation classgroup [Optional]
    • CreatingFramework – creating a framework application? [Required]
    • FrameworkLayer – the framework layer [Optional]
    • FrameworkClassGroup – the framework classgroup [Optional]
    • BuiltOnApp - the built on application name
    • BuiltOnAppVersion - the version of the built on application
  • Purpose:
    • Setup the default class structure for the application(s) being built.
  • Data transforms referenced:
    • pzSetOrgClasses
      • {Org}, {Org-FW}, {Org-Data}, {Org-Int}
    • pzSetFrameworkClasses
      • {Org-FW-App-Data}, {Org-FW-App-Int}, {Org-FW-App-Work}
    • pzSetDivisionClasses
      • {Org-Div}, {Org-Div-Data}, Org-Div-Int}
    • pzSetUnitClasses
      • {Org-Div-Unit}, {Org-Div-Unit-Data}, {Org-Div-Unit-Int}
    • pzSetImplementationClasses - (varies based on whether building division/unit classes
      • {Org-App}, {Org-App-Data}, {Org-App-Int}, {Org-App-Work}
  • Properties set:
    • Org Layer: pyOrgRootClass, pyOrgIntClass, pyOrgDataClass, pyOrgFWClass
    • App Layer: pyAppLayerClass, pyAppDataClass, pyAppIntClass, pyAppClassgroup
    • FW layer: pyFrameworkLayerClass, pyFrameworkDataClass, pyFrameworkIntClass, pyFrameworkClassGroup
    • Div Layer: pyDivisionLayerClass, pyDivisionDataClass, pyDivisionIntClass
    • Unit Layer: pyUnitLayerClass, pyUnitDataClass, pyUnitIntClass

pxSetRuleSetNames – Data-Application-Configuration

  • Parameters:
    • AppName – implementation ruleset name [Required][Optional - as of 7.2.2]
    • FrameworkName – framework ruleset name [Required][Optional - as of 7.2.2]
    • OrgName – organization ruleset name [Required]
    • DivName – division ruleset name [Optional]
    • UnitName – unit ruleset name [Optional]
  • Purpose:
    • Set the default ruleset names based on parameters passed
  • Properties set:
    • Organization rulesets
      • pyAppRuleSetOrg
      • pyAppRuleSetOrgInt
    • Implementation rulesets
      • pyAppRuleSetName
      • pyAppRuleSetNameInt
      • pyAppRuleSetDivision
      • pyAppRuleSetDivisionInt
      • pyAppRuleSetUnit
      • pyAppRuleSetUnitInt
    • Framework rulesets
      • pyAppRuleSetNameFW
      • pyAppRuleSetNameFWInt

pxPrepareAdvancedSettings– Data-Application-Configuration - (new in 7.2.2)

  • Parameters:
    • ApplicationStructure - application structure (Implementation or Framework) [Optional]
    • ApplicationVersion - application version to be creating [Optional]
    • ApplicationSkin - application skin to use [Optional]
    • OrgClassLayer - organization class layer ([org]-app-work) [Optional]
    • DivClassLayer - division class layer (org-[div]-app-work) [Optional]
    • UnitClassLayer - unit class layer (org-div-[unitclasslayer]-work) [Optional]
    • ApplicationClassLayer - application class layer (org-[applicationclasslayer]-work) [Optional]
    • ClassGroupName - class group name (org-app-[classgroupname]) [Optional]
    • AddUIKit - flag that indicates uikit application layer should be added as a built on application [Optional]
    • AddUIKitExpress - flag that indicates uikit application layer should be added as a built on application [Optional] - (removed in 7.4)
    • PrepareDemoOperators - flag to add demo operators for the application being generated [Optional]
    • SkipRoleNameCloning - flag to skip cloning of role names (either for cloned access groups or default) [Optional] - (new in 7.3)
  • Purpose:
    • Set advanced settings on an embedded page within the new application api to be used during pxSetBasicDefaults to override basic default settings
    • This utility is only applicable when called before Data-Application-Configuration!pxBuildApplication
  • Properties set:
    • pyAdvancedApplicationSettings - embedded page (page definition - Advanced-Application-Settings) containing advanced settings
      • pyApplicationStructure
      • pyApplicationVersion
      • pyApplicationSkin
      • pyOrgLayerClass
      • pyDivLayerClass
      • pyUnitLayerClass
      • pyAppLayerClass
      • pyClassGroupName
      • pyAddUiKitExpressLayer - (deprecated in 7.4)
      • pyAddUiKitLayer
      • pySkipRoleNameCloning

pxSetCasesAndData– Data-Application-Configuration - (new in 7.2.2)

  • Parameters:
    • CaseTypesToClone - case types to clone (page containing a list of case types stored in pxResults) [Optional]
    • DataTypesToLink - data types to link (page containing a list of data types stored in pxResults) [Optional]
  • Purpose:
    • Sets up pyCaseTypesToClone and pyDataTypesToLink clipboard pages at the top level which can be consumed later on by single / bulk preparation API's pxPrepareCasesAndData, pxCloneCaseTypes and pxLinkDataTypes
  • Properties set:
    • pyCaseTypesToClone - embedded page containing list of pxResults for each individual case type to be cloned to the new application
    • pyDataTypesToLink - embedded page containing list of pxResults for each individual data type to be linked to the new application

Default wrapper for preparation

The following activity is the default wrapper for preparing application objects for creation. Calling this activity after setting default top level properties using the activities listed above will prepare the standard list of expected objects for your new application. These include, rulesets, classes, organization, division, unit, application(s), accessgroups and user(s).

pxPrepareApplicationObjects – Data-Application-Configuration

  • Parameters:
    • WorkGroupManager – the manager of the workgroup to be created [Required]
    • TestOpsPassword – the password for any test operators being generated [Optional]
  • Purpose:
    • Prepares rulesets, classes, organization, division, unit, application(s), accessgroup(s), workgroup, and users
  • Activities referenced:
    • pxPrepareRuleSets – prepare the rulesets to create
    • pxPrepareClasses – prepare the classes to create
    • pxPrepareApplications – prepare application(s) to create
    • pxPrepareAccessGroups – prepare access group(s) to create(removed in 7.2.2)
    • pxPrepareSecurityComponents - prepare access group(s), access role(s), access role object(s) (new in 7.2.2)
    • pxPrepareCasesAndData - prepare case type(s) and link data type(s) to the new application (new in 7.2.2)
    • pxPrepareOrgComponents – prepare org, division, unit to create
    • pxPrepareUsers – prepare users to create
    • pxPrepareWorkbaskets - prepares workbaskets to create
    • pxPrepareWorkGroup - prepare workgroup to create

Bulk preparation APIs

The following activities are wrapper activities which call inner activities to prepare a default set of objects for creation. All of the activities exist at the application configuration class.

pxPrepareRuleSets – Data-Application-Configuration

  • Purpose:
    • Set the default ruleset names and prepare default set of rulesets based on configuration settings.
  • Data transforms referenced:
    • pxPrepareRuleSet – Prepares a single ruleset for creation

pxPrepareClasses – Data-Application_Configuration

  • Purpose:
    • Prepare the default set of classes for creation based on configuration and values set during preparation (pxSetClassStructure)
  • Activities Referenced:
    • pxPrepareClass – prepares a single class instance for creation

pxPrepareApplications – Data-Application-Configuration

  • Purpose:
    • Prepares an implementation/framework application based on set-up. Determines whether UI-Kit should be added to the application instance or not.
  • Referenced Activities:
    • pxPrepareApplication – prepares an application instance

pxPrepareCasesAndData – Data-Application-Configuration(new in 7.2.2)

  • Parameters:
    • ImplAppName - the name of the implementation application to prepare cases and data for [Optional]
    • ImplAppVersion - the version of the implementation app [Optional]
    • FwAppName - the name of the framework application to prepare cases and data for [Optional]
    • FwAppVersion - the version of the framework app [Optional]
  • Purpose:
    • Prepares case types and data types to clone / link to the new application
  • Referenced Activities:
    • pxCloneCaseTypes – prepares case types cloned to new application from built on application's cases & data tab
    • pxLinkDataTypes - prepares data types to be linked to new application from built on application's cases & data tab

pxCloneCaseTypes – Data-Application-Configuration(new in 7.2.2)

  • Parameters:
    • CaseTypesToClone - page containing list of case types to be cloned (should be stored in a list of pxResults) [Optional]
    • AppToCloneTo - Application we want to clone to (only needed if you want the case types added to cases & data) [Optional]
    • WorkPoolName- name of the workpool for the case types to belong to [Required]
    • RuleSetName- name of the ruleset to prepare the case types in [Required]
    • UpdateRSPrereqs - update the ruleset that is passed via RuleSetName to have appropriate pre-requisites based on application we are cloning from [Optional]
    • BuiltOnAppName - the built on application name (only needed if updating rs prereqs) [Optional]
    • BuiltOnAppVersion- the built on application version (only needed if updating rs prereqs) [Optional]
  • Purpose:
    • Prepares case types cloned to new application from built on application's cases & data tab
  • Referenced Activities:
    • pxCloneCaseType – prepares a single case type instance for creation

pxLinkDataTypes– Data-Application-Configuration(new in 7.2.2)

  • Parameters:
    • DataTypesToLink - page containing list of data types to be linked (should be stored in a list of pxResults) [Required]
    • AppNameToLinkTo - application name we want to link to [Required]
    • AppVersionToLinkTo - application version we want to link to [Required]
    • RuleSetName - Name of the ruleset for the link [Required]
  • Purpose:
    • Prepares data types to be linked to new application from built on application's cases & data tab
  • Referenced Activities:
    • pzAssociateClassWithApp – associates a data type to an application via a link

pxPrepareAccessGroups – Data-Application-Configuration (withdrawn in 7.2.2, replaced by pxPrepareDefaultAccessGroupsAndRoles)

  • Purpose:
    • Prepares default access groups for creation [Administrator, Author, Manager, User]
  • Activities Referenced:
    • pxPrepareAccessGroup – prepares a single access group instance

pxPrepareAccessGroups – Data-Application-Configuration-Tenant(withdrawn in 7.2.2, replaced by pxPrepareDefaultAccessGroupsAndRoles at Data-Application-Configuration level)

  • Purpose:
    • Prepares default access groups for creation [Administrator, Manager, User]
  • Activities Referenced:
    • pxPrepareAccessGroup – prepares a single access group instance

pxPrepareAccessGroups – Data-Application-Configuration-Express(withdrawn in 7.2.2, replaced by pxPrepareDefaultAccessGroupsAndRoles)

  • Purpose:
    • Prepares default access groups for creation [Author, Manager, User]
  • Activities Referenced:
    • pxPrepareAccessGroup – prepares a single access group instance

pxPrepareSecurityComponents – Data-Application-Configuration(new in 7.2.2)

  • Purpose: Wrapper activity for determining whether we are building on top of a Pega application (PegaRULES, PegaDM, etc), or on top of a framework.
    • Prepares security components for the new application based on whether or new application:

      1) Built on top of Pega OR an application referenced by 0 access groups will prepare default set of access groups / roles

      2) Built on top of an application referenced by at least one access group will clone them as well as all related access role names / objects

  • Activities referenced
    • pxPrepareDefaultAccessGroupsAndRoles – preparing default set of access groups / roles
    • pxPrepareClonedAccessGroupsAndRoles – prepare cloned access groups / roles

pxPrepareDefaultAccessGroupsAndRoles – Data-Application-Configuration(new in 7.2.2)

  • Purpose:
    • Wrapper activity for intelligently determining where the Administrator role should be cloned from as well as additional administrator roles before calling pxPrepareDefaultAccessRoles / pxPrepareDefaultAccessGroups
  • Activities referenced:
    • pxPrepareDefaultAccessRoles– prepares default access role names / objects to be cloned
    • pxPrepareDefaultAccessGroups - prepares default set of access groups

pxPrepareDefaultAccessGroupsAndRoles – Data-Application-Configuration-Tenant(new in 7.2.2)

  • Purpose:
    • Wrapper activity for setting where the Administrator role should be cloned as well as additional administrator roles before calling pxPrepareDefaultAccessRoles / pxPrepareDefaultAccessGroups
  • Activities referenced:
    • pxPrepareDefaultAccessRoles– prepares default access role names / objects to be cloned
    • pxPrepareDefaultAccessGroups - prepares default set of access groups

pxPrepareDefaultAccessGroups– Data-Application-Configuration(new in 7.2.2)

  • Parameters:
    • AdditionalAdminRoles - any additional admin roles that should be added to the Administrator / Author access groups, in addition to AppName:Administrator
  • Purpose:
    • Prepares default set of access groups to be created (Administrator, Author, Manager, User for Impl / FW layer)
  • Activities referenced:
    • pxPrepareAccessGroup– prepares a single access group instance

pxPrepareDefaultAccessGroups– Data-Application-Configuration-Express(new in 7.2.2)

  • Parameters:
    • AdditionalAdminRoles - any additional admin roles that should be added to the Administrator / Author access groups, in addition to AppName:Administrator [Optional]
  • Purpose:
    • Prepares default set of access groups to be created (Author, Manager, User)
  • Activities referenced:
    • pxPrepareAccessGroup– prepares a single access group instance

pxPrepareDefaultAccessRoles– Data-Application-Configuration(new in 7.2.2)

  • Parameters:
    • AdminCloneFrom - where to clone the admin role from [Required]
  • Purpose:
    • Prepares default set of access role names to be created 'AppName:Administrator', 'AppName:Manager', 'AppName:User' which are cloned from the AdminCloneFrom parameter, PegaRULES:WorkMgr4, and PegaRULES:User4 respectively.
  • Activities referenced:
    • pxPrepareAccessRole – prepares a single access role name instance

pxPrepareClonedAccessGroupsAndRoles– Data-Application-Configuration(new in 7.2.2)

  • Parameters:
    • AccessGroupContainer - the containing page for access groups to clone access roles from (the access groups should be stored inside pxResults) [Optional]
    • AccessGroupAppName - the application name this access group will reference [Required]
    • AccessGroupAppVersion - the application version this access group will reference [Required]
    • AccessGroupWorkPool - the workpool for this access group to use [Required]
    • RuleSetName - the ruleset for this access group and access roles [Required]
  • Purpose:
    • Based on a clipboardpage containing a list (stored in pxResults) of access groups, clones each of them as well as applicable access role names / objects that are associated to each access group
  • Activities referenced:
    • pxPrepareClonedAccessGroup - prepares a single access group instance from an existing access group and is updated based on passed parameters

pxPrepareOrgComponents – Data-Application-Configuration

  • Parameters:
    • OrgDefaultAccessGroup – the organization's default access group [Required]
  • Purpose:
    • Prepare organization, division and unit for creation
  • Activities referenced
    • pxPrepareOrganization – prepare organization
    • pxPrepareDivision – prepare division
    • pxPrepareUnit – prepare unit

pxPrepareUsers – Data-Application-Configuration

  • Parameters:
    • OrgName – the organization for the operators [Required]
    • DivName – the division for the operators [Required]
    • UnitName – the unit for the operators [Required]
    • TestOpsPassword – the test operators’ password [Optional]
    • WorkGroupName – the workgroup for the operators [Optional]
    • AdminUserId - the id of the admin user [Optional]
    • AdminUserName - the name of the admin user [Optional]
    • AdminUserEmail - the email of the admin user [Optional]
    • AdminUserExists - Does the admin user already exist (not use at this level, can disregard) [Optional]
  • Purpose:
    • Prepare default set of users for creation [Administrator, Author, Manager, User] for a layer being created (Impl / FW) if built advanced setting is present
  • Activities referenced:
    • pxPrepareApplicationDemoUsers - prepares demo users to create (new in 7.2.2)(removed in 7.4)
    • pxPrepareUser – prepares a single user instance for creation

pxPrepareUsers – Data-Application-Configuration-Express

  • Parameters:
    • OrgName – the organization for the operators [Required]
    • DivName – the division for the operators [Required]
    • UnitName – the unit for the operators [Required]
    • TestOpsPassword – the test operators’ password [Optional]
    • WorkGroupName – the workgroup for the operators [Optional]
    • AdminUserId - the id of the admin user [Optional]
    • AdminUserName - the name of the admin user [Optional]
    • AdminUserEmail - the email of the admin user [Optional]
    • AdminUserExists - Does the admin user already exist (not used at this level) [Optional]
  • Purpose:
    • Prepare / update default set of users for creation [Author only]
  • Activities referenced:
    • pxPrepareUser – prepares a single user instance for creation
    • pxUpdateUser - updates a single user instance if they exist

pxPrepareUsers – Data-Application-Configuration-Tenant

  • Parameters:
    • OrgName – the organization for the operators [Required]
    • DivName – the division for the operators [Required]
    • UnitName – the unit for the operators [Required]
    • TestOpsPassword – the test operators’ password [Optional]
    • WorkGroupName – the workgroup for the operators [Optional]
    • AdminUserId - the id of the admin user [Optional]
    • AdminUserName - the name of the admin user [Optional]
    • AdminUserEmail - the email of the admin user [Optional]
    • AdminUserExists - does the admin user already exist? (if the user exists, update instead of create) [Optional]
  • Purpose:
    • Prepare / update default set of users for creation [Administrator only]
  • Activities referenced:
    • pxPrepareUser – prepares a single user instance for creation
    • pxUpdateUser - updates a single user instance if they exist

pxPrepareApplicationDemoUsers – Data-Application-Configuration(new in 7.2.2) (removed in 7.4)

  • Parameters:
    • BuiltOnAppName - application name to get the list of demo users from template tab
    • BuiltOnAppVersion - application versionto get the list of demo users from template tab
    • OrgName - the organization to associate the users to
    • DivName - the division to associate the users to
    • UnitName - the unit name to associate the users to
    • TestOpsPassword - the password for the demo users
    • WorkGroupName - the workgroup the users belong to
  • Purpose:
    • Prepares demo users for the new application. The list of demo users to be created is determined from the list of demonstration users on the template tab of the built on application name / version
    • The new demo users will have the naming convention of [OperatorName]@[AppName] where the OperatorName is the value in the list of demonstration users for the built on application and the AppName is the name of the new application that the operator is to be associated to.
    • If the demonstration user was listed multiple times and has already been prepared, the entry is updated and any additional access groups the user should have access to are added.
  • Activities referenced:
    • pxPrepareUser

pxPrepareWorkBaskets – Data-Application-Configuration

  • Parameters:
    • WorkGroupName - the workgroup this workbasket belongs to [Optional] [Required] (new in 7.2.2)
  • Purpose:
    • Prepares a workbasket of default@[Org] if it doesn't exist already (new in 7.2.2)
    • Prepares workbaskets for each access group being created
  • Activities referenced:
    • pxPrepareWorkbasket – prepares a single workbasket instance

Single preparation APIs

The following activities are used to prepare a single rule/data instance for creation. All of these activities exist at the application configuration class.

pxPrepareRuleSet – Data-Application-Configuration

  • Parameters:
    • RuleSetName – the name of the ruleset to prepare [Required]
    • RuleSetType – the type of the ruleset to prepare [Required]
      • Org, OrgInt, Div, DivInt, Unit, UnitInt, Impl, ImplInt, Fw, FwInt
    • SkipPreReqs - should pre-reqs be skipped? [Optional]
  • Purpose:
    • Prepare a single ruleset for creation. Add ruleset pre-requisites + add UI-Kit (same logic as App Express)
  • Activities Referenced:
    • pzSetRuleSetPrerequisites – set pre-requisites for ruleset based on the RuleSetType
    • pzAddUiKitPreReq – called if RuleSetType is Org, Impl, Fw [removed in 7.2.2]
  • Properties set:
    • pyRulesetsToCreate – list of rulesets stored on pyApplicationGenerator page

pxPrepareClass – Data-Application-Configuration

  • Parameters:
    • ClassName – the name of the class [Required]
    • ClassLabel – the label for the class [Optional]
    • RuleSetName – the ruleset for the class [Required]
    • ClassType – the type of class (Abstract or Concrete) [Optional]
    • DirectedParent – the directed parent for this class [Required]
    • ClassGroupIndicator – the classgroup indicator (ISCLASSGROUP, HASCLASSGROUP, NOCLASSGROUP) [Optional]
    • ClassGroupName – what is the classgroup [Optional]
    • classFound - if the class already exists [Output parameter] (new in 7.2.2)
    • AlwaysPrepareDADBTable - override if you want to prepare a data admin db table even if the class is not a class group [Optional] (new in 7.3.1)
  • Purpose:
    • Prepares a class instance for preparation
  • Activities Referenced:
    • pxPrepareDADBClassGroup – prepares a classgroup for creation
    • pxPrepareDADBTable – prepares a data table to map the new class to
  • Properties set:
    • pyClassesToCreate – list of classes stored on pyApplicationGenerator page

pxCloneCaseType – Data-Application-Configuration(new in 7.2.2)

  • Parameters:
    • AppToCloneTo– Application to clone to[Required]
    • CaseTypeClass – The class of the case type to clone [Required]
    • DesiredCaseTypeClass - The class you would like the case type to have after being cloned [Optional]
    • DesiredCaseTypeClassGroup - the classgroup you would like for the new case type class to belong to (only necessary if the case type class isn't a class group itself) [Optional]
    • ClassLabel– The label for the cloned class [Optional]
    • ClassDescription - The description for the cloned class [Optional]
    • WorkTypeName - the work type name (added to application work metadata). [Required]
    • WorkPrefix - the work prefix (prefix for work objects for this case type). [Optional]
    • ShowInNewWorkMenu - should this case type be shown in create menu? [Optional]
    • RuleSetName - name of the ruleset for this case type and class to be created in [Required]
    • WorkPoolName - name of the work pool that this case type's class will belong to [Required]
  • Purpose:
    • Prepares a case type and associated class for creation. If this case type has child case types listed, then ensure that the property pyCaseTypesToClone contains the child case types that are listed, or else preparation may fail due to the API not knowing what the child case type class should become.
  • Activities Referenced:
    • pxPrepareClass – prepares a class for creation
  • Properties set:
    • pyCaseTypesToCreate - list of case types stored on pyApplicationGenerator page
    • pyClassesToCreate - list of classes stored on pyApplicationGeneratorPage
    • pyWorkTypeClassesToCreate - list of work type classes stored on pyApplicationGenerator page

pxPrepareDADBClassGroup – Data-Application-Configuration

  • Parameters:
    • ClassGroupName – the key for the classgroup [Required]
    • ClassName – the class to refer to [Required]
    • Label – the label for the classgroup [Optional]
    • Description – the description for the classgroup [Optional]
    • RuleSetName – the ruleset for the classgroup [Required]
  • Purpose:
    • Prepare data admin db classgroup
  • Properties set:
    • pyClassGroupsToCreate – list of classgroups stored on pyApplicationGenerator page

pxPrepareDADBTable – Data-Application-Configuration

  • Parameters:
    • BaseDerivesFrom - app you are built on's workpool [Required]
    • ClassName – the key for the table (the new class being created) [Required]
    • Label – the label for the data table [Optional]
    • Description – the description for the data table [Optional]
    • RuleSetName – the ruleset for the data table [Required]
  • Purpose:
    • Prepare a dedicated table for creation to map the referenced class + objects to in the DB
  • Properties set:
    • pyDatabaseTablesToCreate – list of db tables stored on pyApplicationGenerator page

pxPrepareOrganization – Data-Application-Configuration

  • Parameters:
    • OrgName – the name of the organization [Required]
    • OrgLabel – the label of the organization [Optional]
    • RuleSetName – the ruleset for the organization [Required]
    • DefaultAccessGroup – the default accessgroup for the organization [Required]
    • TopLevelClass – the top level class for the organization [Optional]
  • Purpose:
    • Prepares an organization record for creation
  • Properties set:
    • pyOrganizationsToCreate – list of organizations stored on pyApplicationGenerator page

pxPrepareDivision – Data-Application-Configuration

  • Parameters:
    • OrgName – the org this div belongs to [Required]
    • DivName – the name of the division [Required]
    • DivLabel – the label of the division [Optional]
    • RuleSetName – the ruleset of the division [Required]
  • Purpose
    • Prepares a division to create
  • Properties set:
    • pyDivisionsToCreate – list of divisions stored on pyApplicationGenerator page

pxPrepareUnit – Data-Application-Configuration

  • Parameters:
    • OrgName – the org this unit belongs to [Required]
    • DivName – the div this unit belongs to [Required]
    • UnitName – the name of the unit [Required]
    • UnitLabel – the label of the unit [Optional]
    • RuleSetName – the ruleset of the unit [Required]
  • Purpose
    • Prepares a unit to create
  • Properties set:
    • pyUnitsToCreate – list of units stored on pyApplicationGenerator page

pxPrepareApplication – Data-Application-Configuration

  • Parameters:
    • AppName – the application name [Required]
    • AppLabel – the application label [Optional]
    • AppDescription – the application description [Optional]
    • ApplicationSkin - the skin for the application's skin to inherit from [Optional] (new in 7.2.2)
    • BuiltOnApp – the built on application [Required]
    • BuiltOnAppVersion – the built on application version [Required]
    • ProjectMethodology – the methodology for the app (scrum, pegabpm) [Optional]
    • isFWLayer – is this a framework layer application? [Optional]
    • addUIKit – should UI Kit be added to this application’s ruleset list as a built on (changed in 7.2.2) [Optional]
    • addUIKitExpress -- should UI Kit express be added to this applicationas a built on (new in 7.2.2) [Optional] - (removed in 7.4)
  • Purpose:
    • Sets up the application record for creation
  • Activities referenced:
    • pxPrepareSkin - prepares a new skin for this application which inherits from either the provided ApplicationSkin parameter, or the built on application's skin if not provided.
    • pxPrepareProduct - prepares product rule for the new application
  • Properties set:
    • pyApplicationsToCreate – list of applications stored on pyApplicationGenerator page

pxPrepareSkin - Data-Application-Configuration (new in 7.2.2)

  • Parameters:
    • SkinName - the name for the application skin to be prepared [Required]
    • RuleSet - the ruleset for the skin [Required]
    • RuleSetVersion - the ruleset version for the skin [Required]
    • InheritFrom -the skin that this skin should inherit from [Required]
  • Purpose:
    • Sets up the skin for creation with the desired name and inherit from
  • Properties set:
    • pySkinsToCreate - the list of skins stored on pyApplicationGenerator page

pxPrepareProduct - Data-Application-Configuration (new in 7.4)

  • Parameters:
    • ProductName - Name of the product [Required]
    • ProductVersion - Version of the product [Required]
    • ProductLabel - Label of the product [Optional]
    • RuleSet - Ruleset to place new product in [Required]
    • RuleSetVersion - Ruleset version to place new product in [Required]
  • Purpose:
    • Sets up the product for creation with the desired name and version
  • Properties set:
    • pyProductsToCreate - the list of products stored on pyApplicationGenerator page

pxPrepareAccessGroup – Data-Application-Configuration

  • Parameters:
    • AppName – the application to reference [Required]
    • AppVersion – the application version to reference [Required]
    • AccessGroupSuffix – the suffix for this accessgroup i.e. ‘Administrators’ [Required]
    • AccessGroupType – the type of access group this is i.e. Admin, Manager, User [Required]
    • AccessGroupLabel – the label of the accessgroup [Optional]
    • PrimaryPortal – the primary portal [Optional]
    • SecondaryPortal – the secondary portal [Optional]
    • PortalsList - comma delimited list of portals (overrides primary / secondary)
    • PrimaryRole – the primary role [Optional]
    • SecondaryRole – the secondary role [Optional
    • ThirdRole – a third role [Optional]
    • RolesList - comma delimited list of roles (overrides primary, secondary and third)
    • RuleSetName - the ruleset to go into
    • WorkPool - the workpool for this access group (new in 7.2.2)
  • Purpose:
    • Prepare a single access group instance for creation.
  • Properties set:
    • pyAccessgroupsToCreate – list of access groups stored on pyApplicationGenerator page

pxPrepareClonedAccessGroup – Data-Application-Configuration(new in 7.2.2)

  • Parameters:
    • AccessGroupPage – the access group page that is to be cloned [Required]
    • AppName - the name of the app this access group references [Required]
    • AppVersion - the version of the app this access group references [Required]
    • WorkPool - the classgroup for the application [Required]
    • RuleSetName - the ruleset for this access group [Required]
  • Purpose:
    • Update a single access group instance that is intended to be modified with the provided parameters and created
  • Activities referenced:
    • pxPrepareAccessRole - prepares a new access role for each access role on the access group
  • Properties set:
    • pyAccessgroupsToCreate - list of access groups stored on pyApplicationGenerator page

pxPrepareAccessRole– Data-Application-Configuration(new in 7.2.2)

  • Parameters:
    • AccessRoleName – the name of the access role to be created [Required]
    • AccessRoleLabel - the label for the access role name [Optional]
    • AccessRoleDescription - the description for the access role name [Optional]
    • RuleSetName - the ruleset name for the access role name / objects [Required]
    • RuleSetVersion - the ruleset version for the access role name / objects [Required]
    • CloneFrom - where to clone the access role from [Optional]
    • DependentOn - Dependent on roles. To provide multiple roles, provide comma separate values [Optional]
  • Purpose:
    • Prepares a a single access role name instance and multiple access role object instances assuming that the role name isn't already in the list to be created
  • Properties set:
    • pyAccessRoleNamesToCreate – list of access role names stored on pyApplicationGenerator page
    • pyAccessRoleObjsToCreate - the list of access role objects stored on pyApplicationGeneratorPage

pxPrepareWorkGroup – Data-Application-Configuration

  • Parameters:
    • WorkGroupName – the name of the workgroup [Required]
    • WorkGroupLabel – the label of the workgroup [Optional]
    • WorkGroupManager – the manager of the workgroup [Optional]
    • WorkbasketName – the workbasket referenced [Optional]
    • RuleSetName – the ruleset for this workgroup [Optional]
  • Purpose:
    • Prepare a single workgroup instance for creation
  • Properties set:
    • pyWorkGroupsToCreate – list of work groups stored on pyApplicationGenerator page

pxPrepareWorkbasket – Data-Application-Configuration

  • Parameters:
    • WorkbasketName– the name of this workbasket [Required]
    • OrgName – the organization this workbasket belongs to [Required]
    • DivName – the division this workbasket belongs to [Required]
    • UnitName – the unit this workbasket belongs to [Required]
    • WorkgroupName – the workgroup name [Required]
    • Label - the label for the workbasket [Optional]
    • RuleSetName - the ruleset for the workbasket [Optional]
  • Purpose:
    • Prepare a single workbasket instance for creation
  • Properties set:
    • pyWorkbasketsToCreate– list of workbaskets stored on pyApplicationGenerator page

pxPrepareUser – Data-Application-Configuration

  • Parameters:
    • UserID – the users’ identifier [Required]
    • UserName – the users’ full name [Required]
    • UserEmail – the users’ email address [Required]
    • UserPass – the users’ password [Optional]
    • UserType – the type of user they are (correlates to accessgroup type) [Optional]
    • PrimaryAccessGroup - override the primary accessgroup for this operator [Optional]
    • SecondaryAccessGroup – the secondary accessgroup for this operator [Optional]
    • OrgName – the organization to associate to [Required]
    • DivName – the division to associate to [Required]
    • UnitName – the unit to associate to [Required]
    • WorkGroupName – the workgroup this user belongs to [Optional]
    • RuleSetName - the ruleset for this operator [Optional]
  • Purpose:
    • Prepares a single user instance for creation
  • Properties set:
    • pyUsersToCreate – list of users stored on pyApplicationGenerator page

pxUpdateUser – Data-Application-Configuration

  • Parameters:
    • UserID – the users’ identifier [Required]
    • UserName – the users’ full name [Optional]
    • UserEmail – the users’ email address [Optional]
    • UserPass – the users’ password [Optional]
    • UserType – the type of user they are (correlates to accessgroup type) [Optional]
    • PrimaryAccessGroup - override the primary accessgroup for this operator [Optional]
    • SecondaryAccessGroup – the secondary accessgroup for this operator [Optional]
    • OrgName – the organization to associate to [Optional]
    • DivName – the division to associate to [Optional]
    • UnitName – the unit to associate to [Optional]
    • WorkGroupName – the workgroup this user belongs to [Optional]
    • UpdateAccessGroup - should the user's primary access group be updated? [Optional]
  • Purpose:
    • Updates a single user instance. Only updates specific values if a parameter is provided. Otherwise, will leave operator as it was before.
  • Properties set:
    • pyUsersToCreate – list of users stored on pyApplicationGenerator page

Framework assets

pzPrepareFrameworkAssetsForGeneration – Data-Application-Configuration

  • Purpose:
  • Properties set:
    • pyFrameworkAssetQueuePage – list of assets stored on pyApplicationGenerator page
    • pyCaseTypesToCreate – list of case types stored on pyApplicationGenerator page

Generation Queues

The preparation process setups up pages in the various object generation lists. The generation lists are page list properties generally named like py<object type>ToCreate These list are then processed in the generation apis detailed below.

The following activity is responsible for creating all of the objects which have been prepared for creation and contains robust error handling / tracking enabling for easy debugging.

pxGenerateApplication – Data-Application-Generation

  • Purpose:
    • Logging milestones for debugging purposes, saving all objects prepared previously and committing to the database
  • Activities Referenced:
    • pzTrackMilestone
    • pzSaveObject
    • pzDoCommit
    • pzProcessObjectPostSave
    • pzDoRollback

The following activities are responsible for tracking the current location in the generation queue and reporting back what items have been committed, what items are pending commit and what the error message was. Having access to the current location in the queue, what items have been committed, what items haven’t been committed as well as an informative error message makes debugging a lot easier.

pzTrackMilestone – Data-Application-Generation

  • Parameters:
    • MessageKeyPrefix - Key of the message to use during this milestone [Required]
  • Purpose:
    • Logs a message if there was a failure w/ the current milestone

pzSaveObject – Data-Application-Generation

  • Parameters:
    • ObjectPage – the step page to be saved
    • doCommit – should this page be committed immediately or deferred
    • doObjSave - should this object be obj saved?
  • Purpose:
    • Save the object passed in. If an error occurs handle the error and report it.
  • Activities Referenced:
    • pzDoCommit – commits all uncommitted records and logs status
    • pzHandleError – handles an error and reporting/logging pertinent information

pzDoCommit – Data-Application-Generation

  • Purpose:
    • Logs current status. Update list of committed items/pending items.
  • Activities Referenced:
    • pzHandleError – handles an error and reporting/logging pertinent information
  • Properties set:
    • pyHandlesOfItemsCommitted – the list of items committed so far in the transaction
    • pyHandlesOfItemsPending – list of items that were pending commit up to this point

pzHandleError – Data-Application-Generation

  • Parameters:
    • ObjectPage – the object being saved
  • Purpose:
    • Handles any errors that are encountered during generation process. Copies errors and converts to a page list and appends errors from list to the log.

API Record Status

Failure status will return a message the represents the milestone that being processed when the failure occured. A Page .pyError will exist that contains a pxResults list of errors encountered.

Project Delivery Developer Knowledge Share
Share this page LinkedIn