Overview
Loops are used in the Document Designer to dynamically expand a section of content by iterating over a set of data. Loops can be added to the following components:
- Sections
- Text Elements
- Table Elements
- Table rows
- XSL Snippet Elements
- Embed Document Elements
If a Loop is applied to a Section and configured to loop over Model Line Items, then a new Section will be created in the output for each Model Line Item that is present on the Transaction. Attribute values in each Section in the output will correspond to a different Model Line Item on the Transaction, effectively creating a new page or pages in the output for each Model on the Transaction.
Administration
To add a Loop to a Section, Text Element, Table row, or XSL Snippet Elements:
- Select the component that the Loop will be added to.
- Click the Loop button (
) in the Dynamic Content Bar. - Select a set of data to loop over from the Loop On drop-down.
- Optionally select an attribute to sort by from the Sort By drop-down.
- Optionally select a sort type from the Sort Type drop-down.
- Optionally add a Filter to the Loop by clicking Yes for Filter. For more information on Filters, see the topic Filters.
-
Click OK to save the Loop.
A Loop icon is added to the component in the Template Flow.
Click the Loop icon on the component, or the Loop button in the Dynamic Content Bar when the component is selected, to modify or delete the Loop.
| Property | Options Available | Required | Description |
|---|---|---|---|
|
Loop On |
|
Yes |
The set of Transaction data that will be looped over. Selecting All Line Items means that both Model Line Items and Part Line Items will be looped over. |
|
Sort By |
All Sub-Document attributes are available to sort by. |
No |
The Sub-Document attribute that determines the order in which looped over data will be displayed in the output. If no attribute is selected, looped over data will appear in the same order as the line items appear on the Transaction. |
|
Sort Type |
|
No |
Determines if the Sub-Document attribute being used to sort by will be sorted from lowest value to highest value (ascending) or highest value to lowest value (descending). If the Sub-Document attribute is a Text attribute, ascending will be alphabetical and descending will be reverse-alphabetical. |
|
Filter |
|
NA |
Determines if data will be filtered out and not used in the Loop based on a set of conditions. For more information on Filters, see the topic Filters. |
Looping Over a Configuration Array Set
A Loop must be nested within another Loop in order to loop over each line in a Configuration Array Set. The “outer” Loop must exist on a Section or a Table row, and it must loop over either All Line Items or Model Line Items.
The nested Loop can be created on a Table row, a Text Element, or an XSL Snippet Element. To configure the nested Loop to loop over a Configuration Array Set:
- Open the Loop.
-
Select Configurable Array Sets from the Loop On drop-down.
The Configurable Array Set field appears.
-
Select the desired array set from the Configurable Array Set drop-down.
- Click OK to save the Loop.
In CPQ, filtering removes data from the output so that what appears meets criteria that you define. Filtering in a loop enables you to restrict the results returned by a certain criteria.
For example, you might want to filter a Table row that has a Loop applied to it so that only discounted parts are shown in the output. Without a Filter, the Loop on the table row will repeat the row for every part on the Transaction. A Filter can be added to the Loop to determine which parts on the Transaction should be looped over.
- Open the Loop.
-
For Filter, click Yes.
The Filter pane appears in the Loop window.
-
Begin typing Filter conditions. As you type, a combination of literal values, operators, Sub-Document Attributes, Main Document Attributes, and Configuration Attributes will be suggested. When the desired component is suggested in the list, click on it to add it to the Filter.
-
Continuing adding components to the Filter until the condition is logically complete.
In this example, a line item will only be looped over if its value for the Sub-Document Discount attribute is greater than zero.
- Click OK to save the Filter and the Loop.
Administrators can use newly supported string functions, date functions, and a between function for numbers.
String Functions
Oracle CPQ supports the following string functions in conditions and loops.
|
Function |
Returns |
Details |
|---|---|---|
|
contains (string1, string2) |
Boolean |
Search string1 for existence of string2 |
|
isNumber(string) |
Boolean |
Returns true if string is numeric |
|
startsWith (string1, string2) |
Boolean |
Checks whether string1 starts with string2 |
|
endsWith (string1, string2) |
Boolean |
Checks whether string1 ends with string2 |
|
isBlank (string) |
Boolean |
Returns true if string is empty, blank, or null |
Date Functions
Oracle CPQ supports the following date functions in conditions and loops.
|
Function |
Returns |
Details |
|---|---|---|
|
isBefore (date1, date2) |
Boolean |
Returns true if date1 is before date2 |
|
isAfter (date1, date2) |
Boolean |
Returns true if date1 is after date1 |
|
equals (date1, date2) |
Boolean |
Returns true if date1 is equal to date2, including time |
|
equalsIgnoreTime (date1, date2) |
Boolean |
Returns true if date1 is equal to date2, ignoring time |
|
dateBetween (date1, date2, date3) |
Boolean |
Returns true if the value to check is between start of range and end of range (inclusive) |
Between Function for Numbers
Oracle CPQ supports a between function for numbers in conditions and loops.
|
Function |
Returns |
Details |
|---|---|---|
|
between (number1, number2, number3) |
Boolean |
Returns true if number1 is between number2 and number3 |
Administrators can convert a Loop to an Advanced Loop that displays in XSL format. An Advanced button displays on the Loop dialog. After opening the dialogs, administrators can go directly to Advanced mode by clicking the Advanced button.
The Loop dialog by default shows All Line Items selected from the Loop On drop-down menu.
Even when no filter is applied, clicking Advanced will construct a basic XSL Loop from the default Loop On selection of All Line Items.
