Switch Rules are a subset of rules you can define once but use multiple times throughout your Ruleset (Version 2 only). They operate similarly to switches in Java by giving you the ability to filter a generic list of objects. Unlike Java, a Switch will exit automatically as soon as a case is matched. Switch rules must contain Type Guards, Case Conditions, or both.
When using Switch Rules, you will need to understand how Cases, Case Conditions, and Type Guards are used and selected in the Ruleset editor. You must also how to recognize when Switch Rules can be used. Clarify helps by using a “choice” label in the Ruleset editor.
Types, sub-types, and the Choice label
A recent enhancement to the Ruleset editor now includes the “Choice” label, which helps you identify those rules which can incorporate the use of Switch Rules and Methods. This visual cue lets the user know that a Switch Rule should be used – something that’s not always obvious.
First, a few terms used here:
Type: an object type.
Sub-type: An extension of another type.
Choice Type: a type that has sub-types. Choice Types can also be thought of as generic types.
When a type has a sub-type (Choice type), then the Choice label will appear next to it in the source and/or target Schema pane of the editor, as shown here. This lets you know that you can use a Switch Rule on that Choice type using Type Guards to match on a specific sub-type. Type Guarding allows you to narrow down an object type within a conditional block.
In the next example, we see in that List<Type> Types has a Choice label. When we create a Switch Rule, we can see the two sub-types: SubTypeA and SubTypeB. It’s important to note that these sub-types aren’t viewable until the Switch Rule and Method have been created.
Choice Types as target
While at least one Source Type is required, Target Type is not. However, if your target is a generic reference (Choice Type), thereby requiring you to create a specific type, you can have Clarify create a target parameter. You can set the Method to create the selected target type when called. To do this, refer to “Using Methods for use in a Ruleset”.
Important note if using existing Connector Schemas (ObjSchema) or custom XML Schemas (v2) prior to Studio v5.0.8
Please review these required steps which must be taken in order to update resources so that Choice Types can be identified.
For Connector Schemas
The Connector Schema is a specialized Schema (NetSuite/Salesforce.ObjSchema) that handles complex data structures from XML, and is generated by Clarify as part of its Cloud Connector support for Salesforce and NetSuite applications.
Action: Perform a Connector Project Update for any Connector Projects using Object Schemas. This is explained in Updating Connector Projects.
For custom XML Schemas (v2)
Action: Update the XML Schema Bindings. See the Update Existing Bindings section as detailed in Creating XML Schemas (for Version 2 Rulesets).
- Cases can only call Ruleset Methods;
- A matched Case automatically "breaks" (unlike Java) which means that no more matching is attempted.
When looping over a generic list of Objects, a Type Guard is used to match on a specific Type. Type Guarding allows you to narrow down an object type within a conditional block.
Switch Rules using Type Guards support integration with Salesforce, NetSuite, and other cloud applications, due to their type hierarchy. As such, these are currently supported with the Object Schema only. Two examples of Type Guards are highlighted here.
To remove a Type Guard from a Case, you must add a Case Condition.
Clarify prevents you from deleting a Type Guard unless a Case Condition exists (and vice-versa).
Switch Rules with Type Guards and Case Conditions (for Object Schemas only)
There may be a scenario when a Source Schema has an Object containing a flag that will determine what it gets mapped to target-side. Since it is the same type of Object, a Type Guard is not enough to match. You must use a condition over the Object's flag to improve the condition.
Switch Rules with Case Conditions and no Type Guard (for non-Object Schemas)
If using Switch Rules with a Schema other than the Object Schema, then only Case Conditions are supported. When a switch case provides a Case Condition in place of a Type Guard, the only difference between other rule types containing a condition is that the case will match once and break. Any cases below the matched case will not be evaluated.
Switch Rules that do not use Type Guards can still be used to filter a generic list.
- Select a Case;
- Right-click and select Add Case Condition.
In some situations, you may want to perform an operation even if no Cases are matched; to do this, the Switch Rule provides a Default Case, which is only called when there is no other match in the Rule.
A Switch Rule may contain a Default Case, which will appear as the last Case in a Switch Rule. The Default Case can be used to perform a task when no other Case in the Switch Rule is matched. A Default Case does not contain any Type Guards or Conditions. Here is an example:
- Select the Switch Rule or case within the Switch Rule;
- Right-click and select Add Default Case.