Working with Variables

If you have characteristic value variables saved in an SAP BI query or query view, they are available on the Variables input port of the data service. Model a variables input form to allow users to enter values for the variables at runtime on the portal before executing the query. If you have a mandatory variable, you must model an input form for it or the query will fail to execute properly.

When using variables in input forms in Visual Composer, you need to use the proper selection syntax in the input field. In addition, whereas regular input fields take the Key value (_key) of a characteristic, variable input fields take the Key (External Display) (_ext_key) value. For these reasons, we recommend you use value help to generate the proper value and selection syntax. This procedure is described below.

Prerequisites

As outlined in Work with SAP BI Systems
SAP BI query or query view with one or more variables

Note Note

Although this procedure relies on an SAP BI system created with the SAP BI Connector on the portal to fully leverage BI capabilities, variables are also supported in systems created with the BI XMLA Connector.

End of the note.

Procedure

Model the basic elements -
Create the data service, variables form, and table that form the basis of the model:
1. On the Find Data Services task panel, select an SAP BI data service (see Find Data).
2. Locate a query or query view that contains variables, and navigate into the Variables folder. Optional variables appear with a green equals sign. Mandatory variables appear with a red equals sign:
  
  Note
  Note on mandatory variables:
  
  With the Variables port on the data service selected, any mandatory variables display in the Field section of the Configure Element task panel appended with an asterisk and marked as Required. Before you can deploy a model with a mandatory variable, you must either provide a value for the variable in the field properties, or uncheck the Required checkbox.
  
  End of the note.
3. Select the query or query view and drag it to the workspace in an iView.
4. Drag from the data service's Variables port and choose Add Input Form.
5. Drag from the data service's Output port and choose Add Table View, and select the fields to display in the table.
6. Select the fields to display in the variables form:
  Double-click the Variables Form, and in the Field section of the Configure Element task panel, select the variables for which you want to provide input when the query is executed at runtime on the portal, keeping the SUBMIT button also selected:
  
  Note
  
  If you have mandatory variables, you must keep these on the form.
  
  End of the note.
7. Save the model.

Explore the required input syntax -

At this point, your model is functionally complete, and you could deploy it to the portal, enter values in the variable fields, and execute the query. However, you need to know the proper selection syntax to enter in each of the input fields. We explore that in this section, but we recommend you add value help, which provides the proper values and syntax for each variable type (which we cover in Step 3, below).

About SAP BI Variable Selection Types

In the query's definition, you can configure SAP BI characteristic value variables that allow you to provide different kinds of selections. For example, you can configure a variable to select single values, multiple values, or a range of values. These are called "display areas" of variables in SAP BI, and each requires a specific type of syntax in an input field in Visual Composer.

Variable Types and Visual Composer Field Syntax

The following table lists the display areas for variables in BI, the corresponding value help type in Visual Composer, and the syntax required by Visual Composer in the input field by each. Note that with variables, you must pass the Key (External Display) (*_ext_key) value of the characteristic to the field. "Value" in the syntax column refers to this value:

Field Syntax
BI Variable Display Area	Visual Composer Value Help Type	Input Field Syntax	Examples
Single Value	Single Selection	`[Value]`	`1612` (the single value 1612)
Multiple Single Values	Multiple Selection	`[Value`1`];[Value`2`];[Value`3`] ...`	`1612;1614` (1612 and 1614)
Interval	Interval Selection	`[Value`(Start)`]:[Value`(End)`]`	`07/2004:12/2004` (the range from 07/2004 to 12/2004)
Selection Option	Selection Options	`[Value]:[Value`(End - optional)`]:`Operator`:I`(Includes) or `E`(Excludes) Available Operators: `EQ` - Equal to `GE` - Greater than or equal to `GT` - Greater than `LE` - Less than or equal to `LT` - Less than `BT` - Between	`1592::EQ:I;1612:1614:BT:I` (include the single value 1592 and the range from 1612 to 1614) `1614::GE:I;6512::EQ:E` (include all values greater than or equal to 1614 except 6512) `1552::LT:I;4000::GT:I` (all values less than 1552 and greater than 4000)

Note Note

SAP BI precalculated value set variables are not supported in Visual Composer.

End of the note.

Add value help to the input field -
Adding value help to the input form will not only help to select the right value to pass along to the form, but will create the syntax for each variable selection type for you.
1. On the Layout board, right-click a variable input field and choose Add Value Help from the context menu.
2. On the Add Value Help for Selected Input Field screen, notice that Visual Composer recommends the type of value help to use. For variables, you must accept the recommended type, which corresponds with the display area configured in the variable itself. Uncheck the Hide advanced configuration options (BI systems only) checkbox.
3. On the Select Data Service screen, browse to and select the characteristic that will provide the list of valid variable values.
4. On the Specify Data Service Runtime Parameters screen, you can leave all values as they are by default except Key field.
  The key field is the value that is actually passed on to the input form. The Key and Key (External Display) values are usually the same in characteristics, but when they differ (such as is usually the case for time characteristics), you need to use the Key (External Display) value as input for a variable. Accordingly, select Key (External Display) from this drop-down list. This field is also referred to in Visual Composer as [Characteristic]_ext_key.
5. Click Finish to exit the wizard and generate the value help.
  Once you have completed the wizard screens, you return the Layout board, where you can see that a Value Help button has been added next to each input field where you have configured it.
6. Save the model.
Deploy -
1. Go to the Deploy to Portal task panel and click Deploy to deploy the model to the portal in Adobe Flash format.
2. Click Run [iView name] to view the iView in runtime on the portal.
  When the iView appears on the portal, you see the input form, value help buttons, and table. The query is waiting for you to select variable values before it executes.

Result

Use the value help dialog boxes to not only retrieve valid Key (External Display) values, but to also create the proper selection syntax.

When you are done, click Done in the value help dialog box to exit and transfer the value to the input field. Note that the field now contains the proper field value and syntax for the variable. Click Submit to execute the query with the variable values you configured and retrieve the result for display in the table:

This graphic is explained in the accompanying text.

Note Note

If you have mandatory variables, you must configure values for these before you submit the query (unless you have unchecked the field's Required flag in the model).
Variables that are configured with default values in the query definition pass along that value automatically when the query is executed.
You can leave optional variable fields blank.

End of the note.

More Information

Variables, in the BEx Query Designer documentation
Value Help Configuration Wizard, in the SAP NetWeaver Visual Composer Reference Guide
Filter a BI Query