Lobby Navigation Guideline

• What is Lobby Navigation
• Components in a Destination Page URL
• Destination Page Type
• Query Parameter
  • Parameter Type
  • Attribute
  • Place Holder
• How to Setup a Destination Page URL
• Using Page Parameters For Navigation
• Lobby Navigation For Specific UI Elements
• Passing Page Parameters When Navigating from a Lobby Element to a Lobby Page
• Handling 'NULL' or Empty Values for Filtering in the URL
• Setting Up Complex Logic
• Appendix
• Appendix A: Supported $filter Query Options for Lobby Navigation In IFS Cloud Web
• Appendix B: CSV (Context Substitution Values) for Dates
• Appendix C: Supported URL Examples for $FILTER

What is Lobby Navigation

If you wish to enable end users to navigate to different pages from IFS Cloud by interacting with a component inside a "Lobby Element", you can configure "Navigation" section within the "Element Designer".

Upon accessing any "Lobby Element Designer" interface, proceed by scrolling down to the "Navigation" section located at the bottom.

Figure 1 - Navigation properties

You must construct a destination page URL in the URL address section, which will then be used with lobby elements to navigate to specific destination page inside or outside IFS Cloud.

Components in a Destination Page URL

Prior to constructing a destination page URL, let's examine some of its components:

Figure 2 - Components in a destination page URL

As shown above, a navigation URL consists of following components

• Destination Page Type
• Query Parameter

• Parameter Type

  • Attribute

• Place Holder

Now lets make a detailed examination on each of these components.

Destination Page Type

The destination page URL is determined by the destination page type. For a detailed reference, refer the table provided below outlining the various navigation types.

Type	Format	Example
Page, Assistant, Tree	page//?	page/BusinessActivity/ActivityPage
Assistant	assistant//?	assistant/FndTstPrimaryCI/ContactAssistant
Tree	tree//?	tree/EquipmentObjectStructureNavigation/EquipObjectStructureTree
Quick Report	quickreport/<ReportId>	quickreport/793115
Lobby	lobby/<LobbyPageId>	lobby/f7b1e8db-411e-426b
External URL	<URL>	http://www.ifs.com

Figure 3 -IFS Cloud Web URL path

Query Parameter

Query parameter consist of multiple parameter types, attributes and placeholders which is combined using logical operators (AND, OR, etc...). These page parameters are used to identify the type of data that will be displayed on the destination page.

Parameter Type

Parameters serve distinct purposes, allowing for a range of customization options when navigating within the IFS Cloud. They are employed based on specific requirements and desired functionalities within the application.

Parameter	Supported For	Description
$filter	Page, Tree	Filters the set of returned records in the destination page using the given parameter values. Example: page/ServiceRequest/ServiceBook? $filter =MchCode eq $[MchCode] NOTE: Value for this parameter is specified using the OData $filter syntax. Supported $filter parameters for Lobby navigation in IFS Cloud Web can be found in  Appendix A.
$orderby	Page, Tree	Order by comma-separated list of expressions to sort the items. Default ascending; can order ascending ascand descending desc. Example: page/ServiceRequest/ServiceBook?$filter=MchCode eq $[MchCode] and MchCodeContract eq $[Contract] &$orderby =RegDate desc, RealFDate desc
searchcontext	Page, Tree	Set the search context of the navigated page/tree Example: page/BusinessMails/Listsearchcontext=CustomerId:$CUSTOMER_ID$,FilterFromDate:true
contexts	Page, Tree, Assistant	Set the client context of the navigated page/tree/assistant Example: assistant/AccountMatching/Assistant? contexts =Company:$COMPANY$&$filter=(MatchingNo startswith(FactId%2C%27PR%27) and SimulationVoucher eq 'false')
$action	Assistant	Call the function to initiate the assistant Example: assistant/ExportCompanyTemplateAssistant/Assistant? $action =ExportCompanySetup{InputTemplateId:$[TemplateId]}
startupmode	Page, Tree	It is possible to set the startup mode of a page when navigating from a lobby element. Currently it is possible to set the following startup behaviors for the destination page. 1. Navigate to a page and enable search instead of populating startupmode =search 2. Execute a saved search after navigating into the page This can be done by passing the URL parameter  startupmode ; startupmode =search:<saved search name> Ex: startupmode =search:PlannedOrdersToday
		NOTE: Priority order of searches when navigating into a page. 1.        $filter from the URL 2.        startup mode from the URL 3.        Default startup mode (from user profile) 4.        Startup mode from Page metadata
pageParams	Lobby	Pass page parameters of a lobby page. Example: lobby/9cf30284-04e6-489d-ad25-080c154010e3? pageParams =COMPANY:$COMPANY$,SITE:$SITE$ Page parameters set through this URL parameter will override any page parameters saved in the user profile. Note: In Lobby to Lobby navigation the page parameters of the source lobby will be automatically mapped to the page parameters of the destination lobby. Therefore, there is no requirement to explicitly map out the parameters as above, given that the parameter names are strictly equal.

Note: If you are using more than one parameter for the same navigation, the parameters should be separated using ‘&’.

Example :   page/PlanningUnitsAnalysis/List?contexts=Company:$Company$&$filter=BusinessPlanId eq $BUSINESS_PLAN_ID$

page/PlanningUnitsAnalysis/List?contexts=Company:$Company$&$filter=BusinessPlanId eq $BUSINESS\_PLAN\_ID$

Attribute

An attribute refers to a specific piece of information or parameter that is included to provide instructions or details for the destination page. This attribute can be used to customize the behavior or appearance of the page that is being navigated to.

Place Holder

A placeholder is a variable or symbol used to represent a value that is not known or defined at the time of creating a filter condition or setting up a navigation action. It acts as a stand-in for an actual value that will be determined or provided at a later point in time.

Placeholders are used to dynamically populate data in the destination page after navigation. This means that instead of specifying a fixed value in a filter condition, you can use a placeholder. When the navigation occurs, the placeholder will be replaced with the actual value at runtime.

It is possible to use parameters in the filter conditions to populate data in the destination page after navigation. Following are the types of placeholders supported by framework used in Lobby and general navigation between pages in IFS Cloud Web

Type	Place Holder	Description
Page Parameter	$PLACEHOLDER$	Include page parameters values of the Lobby page. Example: page/CustomerInstallmentsAnalysis/List?$filter=CustomerId eq $CustomerId$
Data Value	$[PLACEHOLDER]	Include data values of the element. Example: page/PlanningUnitsAnalysis/List?$filter=OrderNo eq **$[ORDER_NO] **
CSV (Context Substitution Variable)	#PLACEHOLDER#	Include CSV values. Example: page/PlanningUnitsAnalysis/List?$filter=MainRepresentativeId eq  #USER_ID# NOTE: CSV value formats for dates can be found in  Appendix B.

Note: It is possible to use parameters in the filter conditions to populate data in the destination page after navigation.

How to Setup a Destination Page URL

• First Identify the destination page type within IFS Cloud

Note: You can easily achieve this by navigating yourself to the desired IFS Cloud page and copying the URL section depicted in the diagram below.

Figure 4 -Obtaining the URL type

page/CustomerOrder/Form

• Paste this URL section into the "URL Address" field within the "Navigation" section.
• After that add the "Parameter" and "Place Holder" to the destination page URL

Note: In order to identify "Parameter" & "Place Holder" you can perform any one or more of the following actions

Example: Our objective is to navigate to a specific order page within the "Customer Order" section. Upon selecting the customer name, you will be redirected to an IFS Cloud page containing all orders associated with that customer. Additionally, it is imperative that all other order pages be organized in ascending order based on their respective "Order No."

(Used Parameter Types: $filter, $orderby)

• First sort the orders according to "Order No." (1)

• Access the page search functionality by clicking the page search button (2), and click on the "Customer" dropdown menu to enter a specific customer number to filter and retrieve the corresponding customer order record.

• Once you finish applying all the filters, copy the "Parameter" section along with the "Place Holders" from the URL (3)

Figure 5 -Obtaining Parameters and Place Holders

Note: This method is used as a shortcut to retrieve navigation URL with all the parameters

Figure 6 -Locating parameters and place holders

$orderby=OrderNo%20asc;$filter=%28startswith%28CustomerNo,'1000'%29%29

• Decode this URL section.

$orderby=OrderNo asc;$filter=(startswith(CustomerNo,'1000'))

• Arrange the URL sections to the proper format with "Parameters" & "Place Holders".

$orderby=OrderNo asc

$filter=CustomerNo eq $[CUSTOMER_NO]

Note: Obtaining the Placeholder

To obtain the placeholder, navigate to the "DataSource," scroll down to the "Columns" section, and retrieve the "Column Name" as depicted in the following figure.

Figure 7 - Obtaining the place holder

• Create the finale URL combining all the sections

page/CustomerOrder/Form?$orderby=OrderNo asc&$filter=CustomerNo eq $[CUSTOMER_NO]

• Paste this in the in the designated "URL Address" section within the "Navigation" segment.

Note: Data Type Conflicts

When navigating, the system relies on the data type defined in the database. If there are any discrepancies or conflicts in data types within the destination page URL, the system will generate an error message to indicate the issue. This means that the data type in the database, the data type in the data source, and the data type in the destination page URL must be consistent in order for navigation to function properly. If there are any discrepancies, please fix the data type in the data source.

Example:

Figure 8 - Data type conflict between Database and Data Source

As shown in Figure 8, there's a data type conflict between "Database" and "Data Source" for PART_NO. You can mitigate this issue by selecting the proper data type from the "Data Type" dropdown in the "PART_NO" raw of the "Data Source".

Note: Defining a Data Type for the Placeholder

When creating a destination page URL, there is no need to explicitly specify a data type for placeholders. Upon defining a placeholder, the system will automatically examine the data source, making any necessary adjustments from the backend to ensure compatibility.

Example: In the provided destination page URL below, the user added single brackets ('') to "$[ORDER_NO]" parameter to define it as a character type, this action will prompt an error message.

Figure 9: Unnecessary data type definition the navigation URL

Rather than specifying a data type for the placeholder, follow the provided instructions to construct the navigation URL and prevent unnecessary error prompts.

Figure 10: Proper syntax of a navigation URL

Using Page Parameters For Navigation

When constructing a navigation URL, you can either navigate by using page parameters or data context. Utilizing page parameters in navigation allows for the modification of parameters during runtime, enabling dynamic adjustments to the data displayed on the destination page. The previous section demonstrated how to construct a destination page URL using data context. Now, let's take a look at how to use page parameters to create a destination page URL.

Follow the steps below to create a destination page URL using page parameters.

Example: The objective of this task is to develop a counter-type lobby element that provides a count of orders for each customer. The parameter "Customer_No" serves as the key input for this element. Altering this parameter will dynamically update the displayed count to reflect the number of orders associated with the specific customer number.

• First define a page parameter in the "Where" section of "Datasource Designer"

Figure 11: Defining a Page Parameter

CUSTOMER_NO = $CUST$

• Once you finish defining the parameter, go to "Preview" section of the "Datasource Designer" and click on the "Parameters" button (1) to access the "Page Parameters" slide-out menu
• You can adjust the parameter value from the "Value" column (2).
• Click on the "Preview" button to view the data after adding the parameter (3).

Figure 12: Preview of the data after applying the parameter

• Go to "Element Designer" and follow the same instructions to construct the destination page navigation URL, but make sure to add the parameter for the place holder as shown below.

page/CustomerOrder/Form?$orderby=OrderNo asc&$filter=CustomerNo eq $CUST$

Figure 13: Using page parameters for navigation

Lobby Navigation For Specific UI Elements

Following are some element specific examples on how the Web Access URL Address can be constructed for IFS Cloud Web pages.

List Setup navigation using a attribute value(s) in the selected row.. Example: page/BusinessActivity/ActivityPage?$filter=RepresentativeId eq $[REPRESENTATIVE_ID]
Matrix Setup navigation using the attributes mapped to the X and Y when clicking on a matrix cell Example: page/BusinessActivity/ActivityPage?$filter=RepresentativeId eq $[REPRESENTATIVE_ID] and Objstate eq $[STATE]
Charts (Bar, Line and Pie) Navigate using the attributes mapped to the X axis and series attribute.
Image/ Text Element To set a URL in the Web Access URL field for Image/Text element. Example: page/BusinessActivity/ActivityPage www.ifs.com/news

Passing Page Parameters When Navigating from a Lobby Element to a Lobby Page

Parameters carry information along when navigating between different sections or pages within the IFS Cloud. These parameters can be pre-filled with values. By default, these parameters are automatically transferred to the destination lobby.

However, in some cases, you might need a more tailored approach. This is where the pageParams parameter comes into play. It provides a way to specifically define how the parameters from the source lobby should be mapped to the parameters in the destination lobby.

Figure 14 - adding page parameters

URL Navigation: Mapping different page parameters between lobby pages

It's important to highlight that when you use pageParams, it takes priority over the default behavior. This means that you have full control over the mapping process. Every detail of how the parameters are mapped needs to be explicitly specified under pageParams.

Figure 15 - Using pageParams in URL navigation

In essence, pageParams offers a high level of customization and control over how parameters are handled during navigation, allowing for a more tailored and precise experience for users.

Handling 'NULL' or Empty Values for Filtering in the URL

If the user wants to send null values in the URL the page parameter should be filled using <> symbol. Framework replaces this symbol with ‘null’ in the navigation parameter.

Example: page/TreeControllers/CustomerPage?$filter=Country eq ‘SWEDEN’ and CustomerNo eq null

This filter returns a set of customers whose country is Sweden and has no value for set in the field customer number.

If the value is left empty it is interpreted as the user does not wishes to filter using the parameter.

When navigating the filter segment containing the page parameter placeholders will be dropped.

Example: page/TreeControllers/CustomerPage?$filter=Country eq ‘SWEDEN’

Setting Up Complex Logic

Including complex logic in to the navigation could result in unexpected results.

Examples		Correct Syntax
URL containing multiple types of logical operators (and/or) without brackets	$filter=Atr1 eq $PP1$ and Atr2 eq $PP2$ or Atr3 eq $PP3$	$filter=Atr1 eq $PP1$ and (Atr2 eq $PP2$ or Atr3 eq $PP3$) $filter=(Atr1 eq $PP1$ and Atr2 eq $PP2$) or Atr3 eq $PP3$
Complex ‘not’ statements	$filter=not(contains(Atr1, $PP1$) and contains(Atr2, $PP2$))	$filter=not contains(Atr1, $PP1$) or not contains(Atr2, $PP2$)

Other supported URL examples can be found in Appendix C.

APPENDIX

Appendix A: Supported $filter Query Options for Lobby Navigation In IFS Cloud Web

* Link to OData documentation for $filter query options; OData Documentation>>

* The client renders the URL syntaxes defined in the lobby element.

Appendix B: CSV (Context Substitution Values) for Dates

Following are the date related CSV (Context Substitution Variable) values for searching dates available in IFS Cloud Web so far;

#TODAY#, #TOMORROW#, #YESTERDAY#

- YEAR, MONTH, WEEK
#START_OF_THIS_#	#END_OF_THIS_#
#START_OF_LAST_#	#END_OF_LAST_#
#START_OF_NEXT_#	#END_OF_NEXT_#

Example: #START_OF_THIS_YEAR#, #END_OF_NEXT_WEEK#

It is possible to add, deduct dates from date defined by the CSV value. When using the dropdown, labels are shown as ‘Today’, ‘Start of this month’, etc. but the relevant CSV value will be used in search after picking it from the dropdown.

Scenario: In range (Due Date): #START_OF_THIS_MONTH# to #END_OF_THIS_MONTH#+7

Advanced: DueDate >= ‘#START_OF_THIS_MONTH#’ AND DueDate <= ‘#END_OF_THIS_MONTH#+7’

Example: page/TaxCodes/List?$filter=ValidFrom eq '#TODAY#+2]

page/TaxCodes/List?$filter=(ValidFrom ge '#START_OF_THIS_YEAR#' and ValidFrom le '#END_OF_THIS_YEAR#-21')

Appendix C: Supported URL Examples for $FILTER

• $filter=Atr1 eq $PP1$ and Atr2 eq $PP2$ and Atr3 eq $PP3$ and Atr4 eq $PP4$
• $filter=Atr1 eq $PP1$ and (Atr2 eq $PP2$ or Atr3 eq $PP3$) and Atr4 eq $PP4$
• $filter=(Atr2 eq $PP2$ or Atr3 eq $PP3$) and contains(Atr1,$PP1$) and round(Atr1) eq $PP1$ and contains(Atr3,$PP3$)
• $filter=Atr1 eq $PP1$ and (Atr2 eq $PP2$ or Atr3 eq $PP3$ or (Atr4 eq $PP4$ and Atr5 eq $PP5$)) and Atr4 eq $PP4$
• $filter=Atr1 eq $PP1$ and not contains(Atr1,$PP1$) and Atr3 eq $PP3$ and Atr4 eq $PP4$
• $filter=Atr1 eq $PP1$ and (Atr2 eq $PP2$ or not contains(Atr1,$PP1$)) and Atr4 eq $PP4$
• $filter=Attr1 eq Path.To.Enum’$PP1′ and Atr2 eq $PP2$ and Atr3 eq $PP3$

Notes: In some cases, same filtering achieved using some SQL expressions can be achieved using odata filter as well even though there is no direct mapping between the syntaxes.

Eg: - nvl(X,10) = Y can be written as $filter=(X eq null and Y eq 10) or (X ne null and X eq Y)

When using enumeration values in filter conditions, full qualified name must be used, like the advanced search. $filter =Objstate eq IfsApp.ActivityListHandling.ActivityState'Planned'