Motivation:
This blog focuses on the capability of configuring complex filter expressions using the SAP Build Editor via Condition and Text Expression Editor.
Concept and Need:
The $filter system query option allows clients to filter a collection of resources that are addressed by a request URL. The expression specified with $filter is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response.
The format of valid filter conditions is as follows:
Single filter condition: <filter_property_name> <filter_operator> <filter_operand>
Multiple filter conditions: <filter_property_name> <filter_operator> <filter_operand> and/or <filter_property_name> <filter_operator> <filter_operand>
Most SAP GET APIs have an associated $filter query parameter which enables to fetch a subset of records from a collection satisfying a particular condition.
Parent Blog:
The New Actions Project - Major Changes including the Actions Editor Available Now !!
Condition Editor
Condition Editor is a drop down based interface that allows the action designer to design filter expressions that involve only logical operators. Each filter expression comprises of the following components:
- One or more groups.
- Each group should have at least 1 inner group.
- Each inner group should have at least 1 condition.
Steps to create filter expressions using the Condition Editor:
Example: User wants to fetch the list of all the blocked business partners who are either males or females. The equivalent filter expression will be:
(BusinessPartnerIsBlocked eq true and ((IsMale eq true) or (IsFemale eq true)))
1. Select BusinessPartnerIsBlocked from the Column drop down and equal to from the Condition drop down respectively. The Criteria dropdown can accept values in two different formats.
Either the user can hardcode the values in the editor or choose a parameter reference from the drop down. For this illustration, we hardcode the value to true.
2. Create a new inner group by clicking the Add Inner Group button. The purpose of creating an inner group is to ensure that the last two conditions namely IsMale eq true and IsFemale eq true are grouped and evaluated together.
3. Add the condition IsMale eq true using the same process as in Step 1
4. Create a new condition by clicking on the Add Condition button. Now similarly add the condition IsFemale eq true.
5. Click on the OK button. The text Conditions Applied is shown for the $filter parameter both in the Parameter table and the side panel.
6. Navigate to the Test tab and execute the action.
The 2nd example will show how to construct a filter expression with parameter references. We will use the same example as the one above, but in this case the operand value for one of the filter conditions will be coming from a parameter created in the Parameter table.
1. Create a custom parameter of type boolean BPBlocked in the Parameter table.
2. In the Condition Editor, select BusinessPartnerIsBlocked from the Column drop down and equal to from the Condition drop down respectively. Select ${BPBlocked} from the Criteria drop down.
3. Repeat steps 2,3 and 4 as in the previous example.
4. Click on the OK button. The text Conditions Applied is shown for the $filter parameter both in the Parameter table and the side panel.
5. Navigate to the Test Tab. The parameter BPBlocked should be visible. Select the desired value and execute the action.
This technique ensures that the citizen developer has control on the operand values that are used for defining the filter queries.
Text Expression Editor
Text Expression Editor allows the action designer to enter filter expressions in free text format. The capabilities of this editor extend beyond Condition Editor. User can design filter queries such as:
- Queries with NOT operator - not(CategoryID gt 1 and UnitsInStock gt 0)
- Queries with lambda operators - Products/any(x: x/ProductName eq 'Chai' or x/ProductName eq 'Aniseed Syrup')
- Queries involving functions such as substringof, endswith etc.
- Queries involving arithmetic operators - Price add 5 gt 10
- Queries which require combination of the above query types using logical operators.
Steps to create filters expression using the Text Expression Editor:
Example: User wants to fetch the list of airports in San Francisco. The equivalent filter expression will be:
/Airports?$filter=contains(Location/Address, 'San Francisco')
1. Select the Text Expression tab in the filter dialog.
2. Type or copy-paste the query contains(Location/Address, 'San Francisco') in the editor and press the OK button.
3. The text Expression Applied is shown for the $filter parameter both in the Parameter table and the side panel.
4. Navigate to the Test tab and execute the action.
Like we saw in Condition Editor, the Text Expression Editor too supports filter queries with parameter references. Following screenshots illustrate how a parameter can be used in text expressions:
1. Create a custom parameter Address of type string in the Parameter table. Construct the filter query as shown below
2. Navigate to the Test Tab. The parameter Address should be visible. Provide the value San Francisco and execute the action.
Using the $filter parameter to define filter expressions
The techniques discussed before allow the action designer to design filter queries on behalf of the citizen developer. However, the citizen developer can still go ahead and provide filter queries of his own using the $filter parameter. This filter query will be logically ANDed with the one that is coming from the Condition Editor/ Text Expression Editor. The screenshots below illustrate the same:
The goal of the above editors is to abstract the complexities of designing OData filter queries from the citizen developer. In addition to this, the capabilities to allow operand values for the filter queries via parameter reference or provide filter queries using the $filter parameter, ensure that the citizen developer has decent control on the design of the filter expressions.
Thanks for reading and I hope it helped to understand the concept of creating filter expressions using Action Editor. Please feel free to leave a comment if there are any questions and I would be happy to receive any feedback.
- SAP Managed Tags:
