Context Linking

Available from version 10.0

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:

Preparing data and passing them to the target destination.
- This is a Groovy logic written by Configuration Engineer.
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

See the latest complete list of supported parameters in JavaScript docs, including logic Groovy code samples how to use them in a method call or as URL parameter.

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.

Module	Capabilities

Module	Capabilities
Quoting / Quotes	targetPageAction, targetPageEntityType, targetPageFields, targetPageFilters, targetPageInputs, targetPageItems, targetPageItemsInputs, targetPageItemsStrategy, targetPageTab, targetPageTabState, targetPageComment, targetPageCommentContent, targetPageCommentPlaceholder, targetPageCommentTitle, targetPageConfirm, targetPageConfirmContent, targetPageConfirmTitle
Agreements & Promotions / Agreements & Promotions	targetPageAction, targetPageEntityType, targetPageFields, targetPageFilters, targetPageInputs, targetPageItems, targetPageItemsInputs, targetPageItemsStrategy, targetPageTab, targetPageTabState, targetPageComment, targetPageCommentContent, targetPageCommentPlaceholder, targetPageCommentTitle, targetPageConfirm, targetPageConfirmContent, targetPageConfirmTitle
Rebates / Rebate Agreements	targetPageAction, targetPageEntityType, targetPageFields, targetPageFilters, targetPageInputs, targetPageItems, targetPageItemsInputs, targetPageItemsStrategy, targetPageTab, targetPageTabState, targetPageComment, targetPageCommentContent, targetPageCommentPlaceholder, targetPageCommentTitle, targetPageConfirm, targetPageConfirmContent, targetPageConfirmTitle
Sales Compensations / Compensations Plans	targetPageAction, targetPageEntityType, targetPageFields, targetPageFilters, targetPageInputs, targetPageItems, targetPageItemsInputs, targetPageItemsStrategy, targetPageTab, targetPageTabState, targetPageComment, targetPageCommentContent, targetPageCommentPlaceholder, targetPageCommentTitle, targetPageConfirm, targetPageConfirmContent, targetPageConfirmTitle
Dashboards	targetPageInputs
Company Processes / Configuration Wizards	targetPageInputs
Custom Forms	targetPageFields, targetPageFilters, targetPageInputs, targetPageTab
Model Object	targetPageEntityType, targetPageInputs, targetPageFields
Master Data tables (Products, Product Extensions, Product References, Customers, Customer Extensions, Sellers, Seller Extensions, Competition Data, BoM Data, Data Change Requests)	targetPageFilters, targetPagePreferences

Code Samples

linkCell() – Action from Dashboard provides an example of submitting a quote from a dashboard.

rowSelectionBackEndAction() – Creation of Quote with Selected Products 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.

def controller = api.newController()

controller.addButton("New prefilled Quote", AppPages.QC_NEW_QUOTE, [
  targetPageFields: [
    // "Name of the field": "Value of the field"
    externalRef: 'Quote from button'
  ],
  // List of line items which will be added to the quote
  targetPageItems : ['B-0001', 'B-0011'],
  // Navigate a user to items tab, it is recommended approach when you add items because it can take time
  targetPageTab: 'items',
  targetPageInputs: [
    // "Name of the input": "Value of the input"
    Customer: 'CD-0003'
  ]
], null)

return controller

Duplicating an unsaved CLIC module with autosave on will throw an error as the module was not saved.

From Dashboard to Configuration Wizard

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

def controller = api.newController()

controller.addLink("Wizard: CW form config - prefill", AppPages.MD_WIZARD_PAGE, [
  id              : 10,
  targetPageInputs: [
    TextUserEntry: "Hello World!",
    Margin       : 10,
    Products     : "B-0002",
    InputMatrix  : [
      [name: "CONTEXT", RACI: "R", comment: "no comment"],
      [name: "LINKING", RACI: "A,C", comment: "no comment"],
      [name: "EXPERIMENT", RACI: "A", comment: "With comment", selected: true],
      [name: "WITH", RACI: "I", comment: "Without comment"],
      [name: "INPUT", RACI: "I, A", comment: "no comment", selected: true],
      [name: "MATRIX", RACI: "I", comment: "All comments", selected: true]
    ]
  ]
])

return controller

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).).

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.

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