Context Linking

Contextual actions allow you to create buttons, links and actions for faster workflows across the application.

Benefits

• Reduced Time to Action – Less clicks and less manual switching between modules.

• Reduced Manual Input – Parameters and configuration can be shared across the application.

• Pass actions to target page – You can calculate, recalculate or refresh the data on a target page with the click of a button. 

• Open Dashboards with preselected values and have the dashboard recalculated.

• Wide support across modules – First phase includes Dashboards, Quotes, Rebates, Agreements and Promotions, Sales Compensation , Custom Forms and Configuration Wizards.

Typical Use Cases

A Sales Assistant captures the details from a customer seeking a quote and sends an email to a Sales Executive with an embedded link to create a new Quote. 

A Sales Executive selects multiple products from a Dashboard and clicks a button to create a new Quote with the selected products. 

A Sales Executive creates a new dispute from their personal dashboard, to request an adjustment or review of commission on a closed deal.

A Pricing Analyst selects products from a price list and clicks a button to open a dashboard with the preselected inputs.

Contextual Actions - Usage

• Create a new quote with prefilled values input.

• Trigger an action from within a dashboard.

• Insert items from a dashboard with selected products directly into a Quote.

Architecture

Context Linking allows you to pass data from one module to another. You can have e.g. a dashboard with products and from this dashboard you can create a new quote which contains products selected in that dashboard.

Context Linking consists of two parts:

1. Preparing data and passing them to the target destination.

   • This is a Groovy logic written by Configuration Engineer.

2. JavaScript code implemented at front-end which processes the passed data.

You can send a context from all places where you can create a link, button or URL. The list of target destinations and the type of context which you can pass is limited by capabilities of individual modules.

Context linking is an extension for the target page state. So the data which you want to pass have to be added to the targetPageState object. Or you can put the data directly into URL as URL parameters, but there are limitations.

Sources

From where the context link can be initiated. Generally you can send a context from all places where you can create a link, button or URL. For example, you can make the context link on:

• Dashboard

• Price List / Live Price Grid / Manual Price List

• Quotes listing/detail

• Rebate Agreements listing/detail

• Agreements & Promotions listing/detail

• Sales Compensation Plans listing/detail

• Notification / Notification center (see NotificationApi)

Targets

What destinations can the context link go to and do some action there.

• Dashboard

• Quotes listing / detail / specific tab in detail

• Rebate Agreements listing / detail / specific tab in detail

• Agreements & Promotions listing / detail / specific tab in detail

• Sales Compensation Plans listing / detail / specific tab in detail

• Configuration wizard

• Custom Forms

• Optimization Model Object

Context Linking Parameters

Note: The word “targetPage” of the parameter name can be shortened to “tp”.

• targetPage : string. Name of Page to be redirected to. In Groovy logic code, this parameter is sometimes provided as an argument of a method call, instead of providing this parameter directly. The page names are defined as values of constants available in AppPages interface.

• targetPageAction : string = “RECALCULATE” | “SUBMIT” | “WITHDRAW" | “APPROVE” | “REJECT” | “DUPLICATE”. Action to be triggered on targetPage. For objects of types Q, CT, RBA, CO. Quotes also support “CONVERT_TO_DEAL” | “MARK_AS_LOST”. Custom Forms support “RECALCULATE“ | “SUBMIT“ | “WITHDRAW" | “APPROVE” | “REJECT” (Withdraw, Approve and Reject since version 13.0). Price Lists and Live Price Grids support “RECALCULATE” (since version 13.0).

• targetPageAddLostReason : boolean. Displays a confirmation dialog with options to set lost reason and lost reason comment for Quote context linking event, when using targetPageAction = 'MARK_AS_LOST' (since version 13.0).

• targetPageEntityType : string. Unique name of configured CLIC header type (Quote Type, Agreement & Promotion Type, Rebate Agreement Type, Compensation Type). Can be also used for Custom Form Types.

• targetPageFields : [key:value] Values for out-of-the-box fields of the target page entity.

• targetPageFilters: Applies a simple or an advanced filter to the target page table. Filtering is supported for the following tables (listings): Quotes, Agreements & Promotions, Price Records, Rebates Agreements, Rebates Records, Compensation Plans, Compensation Records, Price Lists, Live Price Grids, Manual Price Lists, Custom Forms.
  If you use the “&" character in a quick filter, you need to encode it manually (%26) (as it is used to separate query string parameters).
  Example: ?tpFilters=sku%20~%200005 (sku contains 0005). For more details, see the ContextLinkingURLParams documentation.

• targetPageInputs : [key:value] Map with values for the input fields/parameters of the target page entity. The inputs can be of both simple and also complex types like Configurator. For example, in case of Configurator, the “key” represents the name of the Configurator input, and the “value” will be a Map with values of the inputs of the Configurator form.
  To set the value of an input nested in a collapsible section, use dot notation.
  Example:

  targetPageInputs: [ // Sets the value of the 'stringUserEntry1_collapsible_row1' input within 'row1' in 'collapsibleSectionWithRows' to "Hello". "collapsibleSectionWithRows.row1.stringUserEntry1_collapsible_row1": "Hello" ]

• targetPageItems : string[] List of items IDs (e.g. list of SKUs) which will be added at targetPage.

• targetPageItemsInputs : LineItemInputs[] Values for the input fields/parameters of the new items.

• targetPageItemsStrategy : string = “append” | “delete”. Strategy for adding new line items. Either append new lines to existing items (default setting), or replace/delete all existing items before adding the new ones.

• targetPagePreference : string. Name of preference which will be applied on the target page. See a list of objects/pages where preference setting via context links is supported.

• targetPageSelection : string. Allows you to pre-select line items in Price List, LPG, and since version 13.0 also Quote, Rebate Agreement, Agreement/Promotion or Compensation Plan detail. This field uses typed ID for Price Lists and LPGs and lineID for Quotes, Rebate Agreements, Agreements/Promotions and Compensation Plans (not SKU!).

• targetPageTab : string = header | items | … . Name of the target tab which should be shown.

• targetPageTabState : string. Typed Id. Can target a specific item on the target tab.

• targetPageTarget = “new” | “same”. Defines if a link is opened in a new browser tab or in the same window. There is also a value “drawer” which is used only in case of contextual actions on price list/grids.

Supported Context Linking Parameters per Target

Not all modules support all parameters. This table maps parameters to modules.

Code Samples

linkCell() – https://pricefx.atlassian.net/wiki/spaces/KB/pages/4370497653 provides an example of submitting a quote from a dashboard.

rowSelectionBackEndAction() – https://pricefx.atlassian.net/wiki/spaces/KB/pages/4367877191 provides an example of creation of a new quote.

From Dashboard to New Quote with Values

This example shows a dashboard with a button which creates a new quote with prefilled fields External Ref, Customer Input and has two line items with products B-0001 and B-0011.

From Dashboard to Configuration Wizard

This example shows how to pass data from a dashboard link to a configuration wizard.

Debugging

It can be challenging to figure out in which format to pass data to the context linking logic. Let's assume that you want to fill in the inputs Date Time, Decimal User Entry and Option in the UserInputs dashboard (https://e2e-aws.pricefx.com/unity/staging/modules/#/dashboards/UserInputs).).

Open

The best way to find out the field names and values is to open Web Developer Tools in your browser and go to the Network tab. Then fill in the data in the dashboard and click Apply Setting.

Open

Then you can use content of that response payload as targetPageInputs in context linking: