rules-rule-obj-flow

Imported from pegasystems/infinity-ai-plugins (plugins/pega/infinity-ai-plugins/claude/resources/25-1/skills/rules-rule-obj-flow/SKILL.md). Install upstream with npx skills add pegasystems/infinity-ai-plugins --skill rules-rule-obj-flow. Copyright stays with the author.

Prerequisite: Load methodology-rule-authoring first

Authoring Notes

Identity constraints

pyFlowType is the flow identity key (with pyClassName). pyWorkClass must always equal pyClassName. These are enforced by the server and will cause save failures if mismatched.

Flow naming

Flow names (pyFlowType) cannot contain hyphens (-). Use PascalCase or underscores. The server's KeyValidate activity rejects names with hyphens.

Navigation map fields

pyFromTasks, pyEndingActivities, and pyStartActivity are auto-regenerated by the Validate activity on every save. However, they may be required in the initial create payload for the server to accept the rule. Include them when creating a new flow; on subsequent updates they will be overwritten by the server.

Empty class values

Use "" (empty string) for blank class entries in pyPagesAndClasses and shape pyClassName. Do not use $None or $none — the OnBeforeDisplay activity normalizes those to "".

Expression decision limitations

EXPRESSION-type Decision shapes (pyDecisionClass: "EXPRESSION") only accept a bare property reference in pyImplementation (e.g., .DoNotAttachCorrespondence, .ResolutionStatus). The property is evaluated as a boolean at runtime.

Not valid in pyImplementation:

• Function calls: pxIsBlank(.pyRouteTo) — rejected by the expression parser
• Operator expressions: .pyLabel == "" — not supported for EXPRESSION decisions

EXPRESSION decisions use Status connectors (pyConditionType: "Status") with pyExpression: "true" or "false", not When/Else connectors.

For operator-based branching, use a Data-MO-Gateway-DataXOR decision with When connectors. When connectors accept both named When rules (e.g., RunningConversionUtility) and inline property comparisons (e.g., .pyAssignedOperator != "").

pyExpressionGadget is absent from all observed production flows and should not be included when creating EXPRESSION decisions via the API.

ScreenFlow differences

ScreenFlow flows (pyCategory: "ScreenFlow" or "ScreenFlowStandard") use a different Start shape class (Data-MO-Event-Start-StartScreenFlow vs Data-MO-Event-Start), a different start shape template (pyFromMODefName: "Start" with pyMOId: "Start62"), ScreenFlow assignments (Data-MO-Activity-Assignment-WorkAction), and ScreenFlow subprocesses (Data-MO-Activity-SubProcess-ScreenflowProcess with pySubProcessCategory: "ScreenFlow"). See the flow-screenflow, flow-shape-start-screenflow, flow-shape-assignment-screenflow, and flow-shape-subprocess-screenflow examples.

Per-shape category stamps

Every shape carries a shape-level pyCategory that varies by flow category:

Per-shape boilerplate fields by category

FlowStandard non-Start/non-End shapes carry pyBaseClass (the work class) and pyUseCaseWorkType (short case-type name). Start and End shapes omit both. ScreenFlow shapes do not carry these fields.

pyTicketShapes also differs:

Shape Types

Shape name prefixes

The numeric suffix is assigned sequentially. Gaps are normal (e.g., END52 does not mean 52 shapes). Uniqueness within the flow is the only requirement.

Unsupported shape types

If the user requests a shape type that does not appear in the table above or in the pxObjClass ↔ pyFromMODefName mapping below, stop immediately and inform the user that the requested shape type is not supported. Do not attempt to author it. List the supported shape types from the table above so the user can choose an alternative.

If the current flow has pyCategory: "ScreenFlow", Approval and Agent shapes are not supported because ScreenFlow flows can only call other ScreenFlows as subprocesses.

pxObjClass ↔ pyFromMODefName mapping

ConversationFlow shapes. AskAQuestion / SendAMessage are supported when paired with pyStructureType: "ConversationFlow" — the pxObjClass is the Data-MO-Activity-SubProcess-Conversation-* subclass family.

Legacy-only — do not author. Spin / SpinEnd (Data-MO-Gateway-Spin / Data-MO-Gateway-SpinEnd) are Visio-era shapes. For spin-off patterns use Data-MO-Activity-SubProcess-Spinoff with pyFromMODefName: "Spinoff".

Common shape fields

Every shape carries these regardless of type:

Start and End shapes use pyMOName: "Start" / "End" on legacy flows; modern Process Modeler may write "" or the pyMOId instead. On recreation, preserve the server's value. On fresh authoring, either convention is acceptable.

Flow-level pyParameters convention

When a flow declares input parameters, the rule-level pyParameters list carries one Embed-MethodParams row per parameter. This convention differs from shape-embedded parameter rows:

When a flow declares no parameters, emit a single empty placeholder row with pyParametersParamName: "" and all other fields blank.

Rule-level Fields by Structure-Type — Canonical Matrix

The single highest-leverage cross-reference in this skill. Eight pyStructureType family-values (or explicit absence) each write a different rule-level field signature. Use this table to answer: "given this structure-type, what rule-level fields do I write, and with what values?" Cells contain the canonical value, (absent) if the field is not emitted at all, (varies) for context-dependent values documented elsewhere, or a back-pointer to the authoritative section. The eight columns are the eight observed family-values including BPMN (pyStructureType field fully absent — its identity signal is pyCategory: "BPMN") and Stub (skeletal flows).

Reading the matrix

• BPMN is the only structure-type where the pyStructureType field is fully absent — not "", not null, not present. The identity signal is pyCategory: "BPMN" alone.
• ConversationFlow is the only structure-type that emits pySuggestedStructureType and pyPageRTE.
• ProcessFlow is the only structure-type with shape-level fractional-inch coordinates. Connector waypoints stay in pixels even on ProcessFlow.
• ScreenFlow is the only structure-type where a self-registering rule name OVERRIDES the taxonomy default for pyFlowType.
• Tickets / annotations / sub-case rollup (pyModifiers / pyStencils / pyCoveredBy) populate only on canvas-modeled flows that wire those features — independent of structure-type taxonomy.

Cross-references

• ConversationFlow 17-field custom-fields cluster: see rule-level-fields.

References

Whenever editing a flow, to ensure you understand the full context, load one or more of these skills

| top-level-rollups | Load when a flow needs rule-level summary lists that mirror shape-level data — pyUseCaseLinks, pyCoveredBy, pyTaskInfo, pxDataReferences | | rule-level-fields | Load when copying or recreating a flow and encountering unfamiliar rule-level fields | | shapes-assignment | Load when authoring an Assignment shape in a flow — routing fields, BPMN differences, ticket wiring | | routing-assignment | Load when configuring who a flow's Assignment routes work to — current operator, worklist, or workbasket | | shapes-utility | Load when authoring a Utility shape in a flow — smart-shape variants (data transform, notification, change-to-stage), plain-activity wiring, and variant differences | | shapes-decision | Load when authoring a Decision shape in a flow (any variant) — required fields, connector wiring, type-specific gotchas | | shapes-genai | Load when authoring a GenerativeAI shape in a flow — pxConnectToGenerativeAI wiring, pyGenAIPage sub-page, placeholder vs configured differences | | shapes-parallel | Load when authoring parallel execution in a flow — SplitForEach iteration, SplitJoin parallel branches, Fork shapes, and pyFromTasks wiring | | connectors-and-mo-id-naming | Load when wiring connectors between flow shapes — condition types, expressions, likelihoods, naming | | routing-decision | Load when a flow's Decision shape has multiple outgoing branches — ordering, pyFromTasks mirroring, multi-destination keying | | flow-schema-vs-modeler-validation | Load when a shape passes schema validation but renders incorrectly in Process Modeler — verification approach and common symptoms |

Verification Checklists

Schema-tolerated vs modeler-significant fields: See flow-schema-vs-modeler-validation — schema validation alone is not sufficient for flow shapes; fields the schema accepts may not render in Process Modeler.

Run the relevant checklist after creating or updating a flow.

After creating a new flow

• Flow (Rule-Obj-Flow): pyRuleFormStatus: Good; pyFromTasks contains expected shape names
• FlowAction (Rule-Obj-FlowAction): same name as the Assignment shape; pyAutoHTML: true
• Backing View (Rule-UI-View): resolved by convention (same name as FlowAction); pyRuleFormStatus: Good
• Decision rule (if any): Rule-Declare-DecisionTable or Rule-Declare-DecisionTree; not a stub
• Activity (if any): pySteps contains real logic, not just a COMMENT
• Flow pxWarnings[0] is empty; no unresolved shape references

After adding a step

• Updated flow: shape appears in pyFromTasks; wiring present in pyLocalActions (Assignment) or pyShapes (Utility/Notification)
• New FlowAction (Assignment step): pyRuleFormStatus: Good; companion View resolved
• New Activity or DT (Utility step): contains real logic, not a COMMENT-only stub
• New Notification (Notification step): pyPurpose == pyRuleName; pyCorrespondence is "{Name} Email" not just "{Name}"
• Flow pyRuleFormStatus: Good; no pxWarnings

After enhancing a step

• Updated FlowAction (Assignment): routing/transitions reflect changes; pyRuleFormStatus: Good
• Updated View (Assignment): field count matches expectation; pxContextMetadata.$fields updated
• Updated Activity (Automation): pySteps contains new logic; no stale COMMENT placeholder
• Updated Decision rule: rows reflect new conditions; pyRuleFormStatus: Good
• Updated Corr template (Notification): pySourceStream updated
• Flow pyRuleFormStatus: Good after any shape re-wiring

After wiring a Notification step (4-rule bundle)

• Rule-Notification: pyRuleFormStatus: Good; pyPurpose == pyRuleName; pyChannelsList has at least one enabled channel
• Rule-Obj-Corr: rule name is "{Name} Email" (not just "{Name}"); pySourceStream contains the email body; pyRuleFormStatus: Good
• Rule-Obj-FieldValue: pyLocalizedValue contains the push/gadget message; pyRuleFormStatus: Good
• Flow Utility shape: pyImplementation = "pzNotifyWrapper"; pyNotificationName and pyCallParams.NotificationName both equal {Name}; pzRuleParamsHolder.pyName = {Name}; pzRuleParamsHolder.pyReferExisting = "Existing"

After wiring a GenAI step (2-rule bundle)

• Rule-Connect-GenerativeAI: pyModelId set; pyUserPrompt references the correct FieldValue; pyOutputProperty set; pyRuleFormStatus: Good
• Rule-Obj-FieldValue: pyLocalizedValue contains the prompt text; pyRuleFormStatus: Good
• Flow GenAI shape: pzRuleParamsHolder.pyServiceName = connector name; pyGenAIPage.pyServiceName = connector name; pyGenAIPage.pyReferExisting = "Existing"; pyImplementation = "pxConnectToGenerativeAI"

After wiring a Utility (Data Transform) step

• Data Transform (Rule-Obj-Model): pyRuleFormStatus: Good; pyProperties contains real assignments; pyCallSuperClassModel: false
• Flow Utility shape: pyImplementation = "pzRunDataTransform"; pyCallParams.DataTransformName = DT name
• Flow pyRuleFormStatus: Good; no pxWarnings

Reflection format

For each rule in a bundle, record:

• what worked: instance key confirmed; pyRuleFormStatus: Good; expected fields present
• what failed: Bad/Warning status; stubs; missing references; or "none"
• next fix: corrective action for each failure; or "none"

Dependent rule detection

For any rule that fails its checklist item, call get-rule with detail="full" on its pzInsKey and inspect references and pxDependencies to identify downstream rules that may also need updating. Report all failing rules and their dependents before returning.

Examples

Example descriptions follow the pattern: Shape type → Shape type (variant) → Shape type. Lead with the flow topology, then a short sentence on when to use the example. Use the shape type names from the "Shape Name Prefixes" table above; add a parenthetical variant only when the specific sub-type matters (e.g., Assignment (worklist), Utility (data transform), SubProcess (approval)).

Rule-level

Shape-level

Component-level