Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Parse Structured rules

Updated on November 23, 2022

Use a Parse Structured rule in conjunction with a Service File rule or the Apply-Parse-Structured method to import structured data to the clipboard. For example, you can import fixed-format flat files from various external sources and platforms.

Note: As a best practice, upload CSV and XLSX files into your application by using the Integration Designer in App Studio. For more information, see Creating a data model from a spreadsheet.

If the source value to be parsed has a simple fixed-format structure where each field has a fixed length and is always present, you can use a map structured rule instead of a parse structured rule. Map Structured rules are simpler to debug and maintain. For more information, see Map Structured rules.

Service and connector forms might reference Parse Structured rules in data mapping. When evaluating the service or connector, the system evaluates the Parse Structured rule.

To execute a Parse Structured rule in an activity, use the Apply-Parse-Structured method.

Tabs on the Parse Structured form

Where referenced

Service and connector rules can reference parse structured rules, as part of the data mapping. For example, a Service File rule can use a parse structured rule to extract specific fields of interest from an input file. For more information, see Service File rules.

Parent class

The Rule-Parse-Structured class is a child class of the Rule-Obj-Activity class. This class is not derived from the Rule-Parse- abstract class.

The parseState object and debugging

As it executes, a Parse Structured rule creates and maintains a Java object in memory named parseState. This corresponds to a method variable in the generated Java.

This object is not visible through the Tracer or the Clipboard tool, but you can use Public API functions to examine it. To do this, include a Java step containing the Public API call:

myStepPage.putString("debug3", Long.toString(parseState.getStreamOffset()) );

where debug3 is a Single Value property. This function places the byte offset position of the Java object into a clipboard value. You can review the clipboard value with the Tracer or Clipboard tool.

Four Pega Platform methods operate on the parseState object:

  • Parse-Byte-Pos (for byte streams)
  • Parse-Char-Pos (for character streams)
  • Parse-Fixed-Binary (for byte streams)
  • Parse-Packed-Decimal (for byte streams)

The result of each method is stored in parseState.lastToken (which can be accessed in a Java step) and is optionally stored as a property value.

The parseState object is defined in the PublicAPI Interface.

This facility is based on* capabilities (not the newer java.nio.* capabilities). The PublicAPI includes methods to query or operate on the object.

Monitoring performance

Through changes to the prconfig.xml file or dynamic system settings, the system can alert you to unusually long Parse Structured executions as PEGA0011 alerts. For more information, see Lengthy service operations.

  • Creating a Parse Structured rule

    To import structured data to the clipboard, create a Parse Structured rule to use in conjunction with a Service File rule or the Apply-Parse-Structured method. For example, you can import fixed-format flat files from various external sources and platforms.

  • Restricting Parse Structured rule execution

    Use the Security tab on the Parse Structured rule form to specify an activity type, and optionally to restrict which users (or other requestors) can execute a rule. This optional security supplants restrictions based on ruleset and version.

  • Using the Steps tab on the Parse Structured form

    To complete the Steps tab on the Parse Structured form, you can use all the methods and instructions that are accepted by the Activity form. You can also use preconditions, transitions, and iterations. Review the following topic to learn about the key differences between the Steps tab on the Parse Structured form and the Steps tab on the Activity form.

  • Unit testing a Parse Structured rule

    You can test a Parse Structured rule directly, separate from the activity or other context in your application in which the rule ultimately operates. By unit testing your Parse Structured rules, you avoid configuration errors and improve application maintenance.

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

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