Parse Structured rules
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.
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.
com.pega.pegarules.pub.runtimeThis facility is based on java.io.* 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.
Previous topic Unit testing a Parse Delimited rule Next topic Creating a Parse Structured rule