Shared criteria in Jitterbit App Builder

Shared criteria allow developers to use variables passed through linked pages or bound panels. These variables are typically generated through binding criteria, which permit an App Builder page link or panel relationship to carry keys that filter data on a target object. For example, a link from a Categories page to a Products page can filter results to show only those products relevant to the chosen category. Beyond simple WHERE clauses, shared criteria extend how these variables can be used throughout the application.

A URL generated with shared criteria typically follows this format:

https://example.dev.zudy.host/app/App%20Name/Page%20Name?FieldName~Shared=2032

How to use shared criteria values

Shared criteria are used to access values in the current runtime context, behaving much like any standard SQL function. When a shared criteria value is included in a data object column, it is treated as a string and becomes real data that can be joined to, used by UI controls, or referenced by subsequent panels. For instance, using shared('EmployeeID') allows you to treat that variable as a standard column within your logic.

These values are highly versatile and can be applied in WHERE clauses to filter results or within CRUD rules to drive inserts and updates. If a rule is executed outside the context of a page (such as when viewing raw results), the function will return the default 'not found' value for the specified data type. Shared criteria are also supported in background events initiated by users, as well as in conditional formatting logic. Furthermore, dynamic substitution allows shared values to appear in cell data and control labels using syntax like {{ CompanyName }}, provided that "Support substitution" is enabled on the control.

The system also handles scenarios where criteria might be missing or when data is being modified. If a page or URL does not contain a matching criteria, the data object will still run, provided the SQL can handle an empty string return. When linking to a page with shared criteria, any newly inserted rows will automatically default columns of the same name to the shared value. Similarly, when switching to an edit state, shared criteria will default themselves onto any null columns that share the same name.

SQL runtime function: Shared

In SQL, you access these variables via the shared() function. This function accepts two parameters: the Name of the criteria to look up and the Data type. Specifying a data type is important; for example, if a criteria is not found and the type is set to UUID or numeric, App Builder will return a blank GUID or a '0' respectively to ensure the resulting SQL does not fail when comparing different data types. An example of this usage is:

SELECT CustomerId, shared('ActiveEmployeeId') FROM Customer WHERE CustomerRegionId <> shared('LastRegion', 'UUID')

Specify shared values

Shared criteria can be defined at either the panel or field level. While they are frequently used on page links, where the URL changes and opens a new page, they are equally supported through panel binding. Targeted pages provide these values to all 'root' panels (those not explicitly bound to others).