ezDynamic Run Controls Developer Guide

Introduction

The ezDynamic Run Control (ezDRC) application component facilitates creation of PeopleSoft run controls that allow process parameters to be defined as either static values or substitution variables. Process parameters defined as substitution variable values are automatically calculated at run-time. Substitution variables are used as parameters when a process is to be run automatically on a recurrence while static values are used for ad hoc execution.

This guide is intended to provide sufficient information for developers familiar with traditional run control development to create new or upgraded processes using dynamic run controls.

The Dynamic Run Control Demo Application

Component Name: EZDRCDEMORC

Navigation: ezSDK > Demos > Application Components > Dynamic Run Control

The ezDRC application component is delivered with a demonstration application intended to provide developers with an example of ezDRC use and a platform for testing custom extensions to ezDRC functionality. Many of the illustrations in this guide are from the demo application. It may be useful to refer to the demo application as you review the concepts presented in this guide.

Understanding Dynamic Run Control Parameters Records

Dynamic parameter values are substitution variables entered on run control pages. Run-time parameter values are resolved substitution variable values used by a specific process instance. Dynamic and run-time parameter values may be stored on separate records or combined on a single record. Separate records provide flexibility and the ability to review instance-specific parameter values but require additional development and maintenance. Separate records may be the preferred approach for new development. A combined record may preferred for upgrading and existing process. The following sections describe how to create dynamic, run-time, and combined parameters records.

Creating Run-Time Parameters Records

Run-time parameters records are automatically populated at execution time with static parameter values and resolved substitution variable values. Developing a run-time parameters record requires the following steps.

  1. Create a SQL Table record definition.
  2. Insert the PROCESS_INSTANCE field into the table and define it as a key.
  3. Add a field to the record for each parameter required by your process, whether static or dynamic.
  4. For dynamic parameter fields only define record edits and default values as needed.
  5. Name the record with a suffix of “RC”.

Example:

Creating Dynamic Parameters Records

Dynamic parameters records are used to store values entered on a run control page. Developing a dynamic parameters record requires the following steps:

  1. Create a SQL Table record definition.
  2. Insert the OPRID and RUN_CNTL_ID fields into the record and define them as keys.
  3. Add record FieldDefault PeopleCode initializing the value of the OPRID field.

Example

<Your Dynamic Parameters Record Name>.OPRID = %OperatorId;

  1. Add a field to the record for each static parameter required by your process.
  2. Set record field defaults and edits as necessary for each static parameter field.
  3. Insert subrecord EZDRCRUNCTLSB into the record.
  4. Name the record with a suffix of “DRC”.

 

Creating Combined Parameters Records

Combined parameters records are used to store both the values entered on a run control page and resolved substitution variable values. Developing a combined parameters record requires the following steps:

  1. Create a SQL Table record definition.
  2. Insert the OPRID and RUN_CNTL_ID fields into the record and define them as keys.
  3. Add record FieldDefault PeopleCode initializing the value of the OPRID field.

Example

<Your Dynamic Parameters Record Name>.OPRID = %OperatorId;

  1. Add a field to the record for each parameter required by your process.
  2. Set record field defaults and edits as necessary for each static parameter field.
  3. Set record field edits for each dynamic parameter field. If a field is defined as required a default value must be specified.
  4. Insert subrecord EZDRCRUNCTLSB into the record.
  5. Name the record with a suffix of “CRC”.

 

Creating Dynamic Run Control Pages

Developing dynamic run control pages requires the following steps:

  1. Create a new page.
  2. Insert subpage PRCSRUNCNTL_SBP (or any other similar run control subpage) at the top of the new page and set record name substitution to record PRCSRUNCNTL.
  3. Place the static parameter fields from you dynamic parameters record on the page.
  4. For every dynamic parameter place a DynaField page control subpage on your page and set record name substitution to record EZDYNFLDWRK. DynaField page control subpages use the naming convention EZDYNFLDxxSBP where xx is the DynaField index number. There are 6 DynaField subpages delivered with the Dynamic Run Control application component.
  5. Place subpage EZDRCRUNCTLSBP at the bottom of your page and set record name substitution to the name of your dynamic parameters record.

Creating Dynamic Run Control Components

Create a traditional run control component using your dynamic run control page and then perform the following additional steps:

  1. On the component PreBuild event:
    1. Import class EZ_DRC:DYNAFIELD:Control.
    2. Create a DynaField object for each of the DynaField page controls used on your run control page. Use the name of your run-time (or combination) parameters record for the second constructor method parameter. (See Appendix A for DynaField class method descriptions.)
    3. Set the Fieldname property for each DynaField object to the name of the corresponding field in your run-time (or combination) parameters record. (See Appendix B for DynaField class property descriptions.)
    4. Register each DynaField object.

Example:

import EZ_DRC:DYNAFIELD:Control;

Local EZ_DRC:DYNAFIELD:Control &oDynaControl;

&oDynaControl = create EZ_DRC:DYNAFIELD:Control(GetLevel0()(1).EZDYNFLDWRK.EZ_FIELDNAME_01, Record.EZDRCDEMORC, False);

&oDynaControl.Fieldname = Field.FROM_DATE;

&oDynaControl.register();

&oDynaControl = create EZ_DRC:DYNAFIELD:Control(GetLevel0()(1).EZDYNFLDWRK.EZ_FIELDNAME_02, Record.EZDRCDEMORC, False);

&oDynaControl.Fieldname = Field.THRU_DATE;

&oDynaControl.register();

&oDynaControl = create EZ_DRC:DYNAFIELD:Control(GetLevel0()(1).EZDYNFLDWRK.EZ_FIELDNAME_03, Record.EZDRCDEMORC, False);

&oDynaControl.Fieldname = Field.FROM_DTTM;

&oDynaControl.register();

&oDynaControl = create EZ_DRC:DYNAFIELD:Control(GetLevel0()(1).EZDYNFLDWRK.EZ_FIELDNAME_04, Record.EZDRCDEMORC, False);

&oDynaControl.Fieldname = Field.THRU_DTTM;

&oDynaControl.register();

&oDynaControl = create EZ_DRC:DYNAFIELD:Control(GetLevel0()(1).EZDYNFLDWRK.EZ_FIELDNAME_05, Record.EZDRCDEMORC, False);

&oDynaControl.Fieldname = Field.FILENAME;

&oDynaControl.register();

Using Dynamic Run Controls with Application Engine Processes

For Application Engine processes population of the run-time parameters record is accomplished a call to the Dynamic Run Control AE Library. Run-time parameters can then be selected from the run-time parameter record by process instance. The process for using Dynamic Run Controls with Application Engines is:

  1. Include record EZDRCAET in the State Record list for your Application Engine process.
  2. Create a step in your process to populate the run-time parameters record. The step will contain two actions:
    1. PeopleCode Action – set the values of state record EZDRCAET fields EZ_RECNAME_DRC and EZ_RECNAME_RC to identify your dynamic and run-time (or combination) parameters records, respectively.

Example – Dynamic and Run-Time Parameters Records:

EZDRCAET.EZ_RECNAME_DRC = Record.EZDRCDEMODRC;

EZDRCAET.EZ_RECNAME_RC = Record.EZDRCDEMORC;

Example – Combination Parameters Record:

EZDRCAET.EZ_RECNAME_DRC = Record.EZDRCDEMOCRC;

EZDRCAET.EZ_RECNAME_RC = Record.EZDRCDEMOCRC;

  1. CallSection Action – call section GET_RC of program id EZDRC.
  1. Select run-time parameter values from the run-time parameters record using the current process instance or combination parameters record as you would a traditional run control record.

Example – Run-Time Parameters Record:

%Select(FROM_DATE, THRU_DATE)

SELECT FROM_DATE

, THRU_DATE

FROM %Table(EZDRCDEMORC)

WHERE PROCESS_INSTANCE = %Bind(PROCESS_INSTANCE)

 

Using Dynamic Run Controls with Other Process Types

To use dynamic run controls with process types other than Application Engine do the following:

  1. Create a job definition with provided AE EZDRCJOB preceding your process.

Navigation: PeopleTools > Process Scheduler > Jobs

  1. Identify the dynamic and run-time parameters records associated with your new process.

Navigation: ezAdd-On Manager > Registry > Setup > Processes Tab

Process Type Select the type of your new process.
Process Name Select the name your new process.
Dynamic Parameters Record Select the name of your dynamic (or combination) parameters record.
Run Time Parameters Record Select the name of your run-time (or combination) parameters record.
  1. Select run-time parameter values from the run-time parameters record using the current process instance.

 

Configuring Substitution Variable Access Controls

By default all run control users have access to substitution variables. You can limit the availability of substitution variables to specific user roles by configuring Dynamic Run Control Template Access Controls. Users not permitted access to substitution variables will not see the blue curved arrow pushbutton to the left of the parameter value edit box and cannot toggle between static value and substitution variable prompts.

Navigation: ezAdd-On Manage > Registry > Setup > Access Controls Tab

Component Name Specify the name of the run control component for which you want to control substitution variable access.
Role Name Specify the role permitted substitution variable access.

Add new rows with the component name to specify addition roles.

 

Creating New Substitution Variables

The delivered set of substitution variables can be extended to meet unique organization requirements. The process for extending the substation variable set requires creating a new method to derive the run-time value of the variable and configuring the variable for access.

Creating New Substitution Variable Calculation Methods

NOTE: There are two Application Packages delivered with the Dynamic Run Control application component: EZ_DRC_BASE and EZ_DRC. ezSDK development standards specify that end users should modify only the extension package, EZ_DRC.

Substitution variable calculation method syntax is as follows

Syntax

substMyNewMethod(Text, VariableName)

Parameters

Text A string containing the substitution variable.
VariableName The name of the substitution variable to be resolved.

Returns

A string with the substitution variable replaced by its run-time value.

Example

class PlugIn extends EZ_DRC_BASE:VARIABLES:PlugIn

.

.

protected

method substPrecedingMonthEndDate(&_RCString As string, &_Variable As string) Returns string;

.

.

end-class;

method substPrecedingMonthEndDate

/+ &_RCString as String, +/

/+ &_Variable as String +/

/+ Returns String +/

Local number &year, &month;

&year = Year(%This.BaselineDate);

&month = Month(%This.BaselineDate) – 1;

If &month < 1 Then

&month = 12;

&year = &year – 1;

End-If;

Return Substitute(&_RCString, &_Variable, DateTimeToLocalizedString(%This.getMonthEndDate(&year, &month), %This.DateFormat));

end-method;

Configuring New Substitution Variables

Navigation: ezAdd-On Manager > Registry > Setup > Substitution Variables Tab

Variable Name Specify the name of a substitution variable. Substitution variable names should begin and end with the pound symbol (#).
Description Provide a description of the substitution variable with adequate detail to guide users in selecting the correct substitution variable for their requirement.
Data Type Identify the data type of the value the substitution variable represents.
Use as Baseline This setting identifies variables that can be used as the baseline value for relative variables. It applies only to date-time variables.
Default Baseline Identifies the baseline variable that will be used in the calculation of relative date and date-time variables when no baseline variable is specified. It applies only to variables identified as baseline variables.
Method Name Specify the name of the variables plugin class method used to calculate the value of the substitution variable.

Appendix A – DynaField Class Methods

The following list of DynaField class methods is not exhaustive. Only the methods commonly utilized by run control developers are presented. For a complete list of methods see the Dynamic Run Control Technical Guide.

Control (constructor)

Syntax

Control(FieldObject, Recordname, Boolean)

Description

The Control associates a DynaField object with a page control and establishes default properties.

Parameters

FieldObject Specify the fieldname field object from the target DynaField page control. Fieldname fields follow the naming conventionUDG2_FIELDNAME_xx where xx is the index number of the page control subpage.
Recordname Specify the name of the record containing the field the DynaField page control will be associated with.
BooleanValue Always False.

Returns

None.

Example

import EZ_DRC:DYNAFIELD:Control;

Local EZ_DRC:DYNAFIELD:Control &oDynaControl;

&oDynaControl = create EZ_DRC:DYNAFIELD:Control(GetLevel0()(1).UDG2DYNFLDWRK.UDG2_FIELDNAME_01, Record.UDG2DRCDEMORC, False);

register

Syntax

register()

Description

Adds a DynaField object to the DynaField page control registry so it can be accessed within a component.

Parameters

None.

Returns

None.

Example

import EZ_DRC:DYNAFIELD:Control;

Local EZ_DRC:DYNAFIELD:Control &oDynaControl;

&oDynaControl = create EZ_DRC:DYNAFIELD:Control(GetLevel0()(1).UDG2DYNFLDWRK.UDG2_FIELDNAME_01, Record.UDG2DRCDEMORC, False);

&oDynaControl.register();

Appendix B – DynaField Class Properties

The following list of DynaField class properties is not exhaustive. Only the properties commonly utilized by run control developers are presented. For a complete list of properties see the Dynamic Run Control Technical Guide.

Fieldname

Description

Use this property to specify the name of the field the DynaField page control will represent. This property is a string value.

This property is read-write.

Example

&oDynaControl.Fieldname = Field.FROM_DATE;

ForceValueNotRequired

Description

Use this property to override the Required record field property the DynaField page control will represent. This property is a Boolean value. When set to true no required validation is performed.

This property is read-write.

Default

False

Example

&oDynaControl.ForceValueNotRequired = True;

ForceValueRequired

Description

Use this property to force require validation processing whether or not the Required record field property the DynaField page control will represent is set. This property is a Boolean value.

This property is read-write.

Default

False

Example

&oDynaControl.ForceValueRequired = True;

Related Articles