Switch Rules

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 know how to recognize when Switch Rules can be used. The Studio UI helps by using a “choice” label in the Ruleset editor.

Types, sub-types, and the Choice label

The Ruleset editor includes the Choice label, which helps you identify those rules that 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 the transformation engine 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 release.

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 the transformation engine 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).

Case

This is the “rule” within the Switch. Similar to the relationship between a Composite Rule and a simple rule, but with two main exceptions:

Cases can only call Methods;
A matched Case automatically "breaks" (unlike Java) which means that no more matching is attempted.

Type Guards

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.

You can not delete 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.

To add a conditional action to a Case:

Select a Case.
Right-click and select Add Case Condition.

Default Case

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:

To create a Default Case:

Select the Switch Rule or case within the Switch Rule;
Right-click and select Add Default Case.

How to use and define

The overall process of using Switch Rules follows this sequence.

Create a Switch Rule in the Ruleset editor.
Select the Switch Rule, and then use the Rule tab in the Properties view to map source data.
Create and define new Cases and/or Case conditions.
Add Methods to each Case.

Create Switch Rules

Use the New Switch option that is available as part of the toolbar in the Rule section of the Ruleset editor. A Switch Rule requires at least one Case. By default, a Switch Rule is created with one Case and new Cases are created with a Type Guard of Object.

To add Cases to a Switch Rule:

Select the Switch Rule;
Right-click and select Add New Case.

Use tabs in the Properties View

The Properties view displays different options based on the Case in the Switch Rule that is selected in the Rules section. This is how you can view and define rules, conditions, and other properties.

Type Guard (tab): In this tab, you can set the Type Guard by clicking the Select Subtype button (). This will display the fully qualified names (FQN) of the Subtypes available for the Type of the element mapped in the Switch Rule. If a Condition has been added to the Case, the Remove Type Guard button will be enabled; allowing you to remove the Type Guard from the selected Case.

Condition (tab):This tab is similar to the Condition tab in Simple and Composite Rules. It allows you to map a Conditional Action to the Case, or remove it from the selected Case if a Type Guard is also provided.

Method (tab): This tab is used to map a Method to a Case in a Switch Rule. You can drag and drop a Method from the Methods pane of the Ruleset editor. After a Method is selected, you can also use this tab to map the Method’s input.

All Method parameters are defined as input, which is slightly different from other Rules in that this allows you to map from the Target schema to the targetParm input (if a Target exists for the Method). Since the targetParm input parameter is a mapping from the Target schema, the editor marks it with by a cross-hair icon ( ).

For more information, see Creating Methods for use in a Ruleset.

Create and define Cases

Use the following right-click options to create and define Cases from the Rules section of the Ruleset editor.

New Case: adds a new Case Rule to your Switch Rule.
Add/Remove Case Condition: adds or removes a conditional action to the selected Case.
Add/Remove Case Method: displays any existing method that can be added to or removed from your Case.

Add Methods to Cases

A Ruleset Method, like a Composite Rule, is used to group rules. An important difference, however, is that the method includes Type parameters that correspond to data types in the source and target of the Ruleset. Methods can also be re-used within the Ruleset, thereby providing better maintainability.

To add a method to a Case:

Select the Case;
Right-click and select Add Case Method, which provides a list of existing Methods. Another option is to drag the specific method from the Methods pane onto the Case or, into the Method tab of the Properties view.
Note: For more information, see the Method topic found in the Using Actions, Variables, and Methods to Define Rules section.