# GB5 BI Platform: Client Admin / Implementation Team Configuration Guide This is the practical "what do I actually click" guide for standing up a BI-backed widget for a client — a KPI card, a chart, a flat table, or a full pivot table. It assumes you already know GB5's general menu/dashboard model; it only covers what's specific to the Portlet config screen and BI-backed widgets. ## Before you start: what you need to know - The screen you'll use is the **Portlet** master screen — reachable from the menu once a `MENUID` has been assigned to it (a one-time setup step for a new client/environment, same as any other new admin screen — see the Developer Playbook for the exact registration keys if you need to wire this up for the first time on an environment). - You need to know **which catalog** the widget should point at (e.g. "Sales" or "Finance," or an existing report someone has already asked to see visualized), and **which dimensions and measures** within it. If you're not sure what's available, open the screen and look — every picker only ever shows what's actually registered and visible for that catalog; you can't pick something invalid. - You can either **pick an existing, already-saved BI View** (reuse a definition someone already built) or **author a new one** from scratch (pick dimensions, measures, and a widget type). A BI View is independent of any one dashboard placement — the same saved view can be reused on more than one dashboard. - Every catalog is one of three kinds, and it affects what you'll see: - **Warehouse** — a governed dataset (e.g. "Sales," "Finance"). Dimensions and measures are pre-registered; nothing further to configure before authoring a view. - **ApiService** — an existing GB5 report, turned into a catalog. You'll additionally see a **Field Mapping Review** section (see below) the first time — someone needs to confirm which fields are dimensions vs. measures before the view picker has anything to work with. - **AnalysisQuery** — a bridge into the separate ad-hoc query designer; if your client already has a query built there, its fields show up here automatically. ## Step-by-step: creating a new BI-backed widget 1. **Open the Portlet screen**, with no existing portlet selected ("-- New Portlet --" in the "Load Existing Portlet" dropdown at the top — this dropdown lets you re-open and edit *any* existing portlet, not just BI ones; leave it on "-- New Portlet --" for a new widget). 2. **Fill in Portlet Code and Portlet Name.** These are your own naming choice — pick something that tells another admin what the widget is at a glance (e.g. code `SALESBYOU`, name "Sales by Organization Unit"). Both are required; the screen will refuse to save without them. 3. **Pick "Analysis" from the Portlet Type dropdown.** (The portlet type keeps its original name — only the underlying engine's naming changed to "BI"; this is the same dropdown entry as before.) This dropdown lists every portlet type GB5 knows about — Analysis is one entry among them, not a separate screen. As soon as you pick it, the catalog picker and the rest of the BI section appear below. If a **Widget Type** dropdown you'd expect to see is missing an option you need (e.g. "Pivot Table" doesn't show up), that's not a bug — the chosen Portlet Type may have been deliberately restricted to a smaller set of widget shapes (see "Widget Type restrictions," below). 4. **Pick a Dataset (catalog).** The dropdown lists every catalog registered and visible to your tenant. This is what the widget will ultimately query against. 5. **Pick or author a BI View:** - **To reuse an existing view** — pick it from the **BI View** dropdown. Its widget type is shown alongside its name (e.g. "Sales by Region (pivot-table)"). Picking one renders that saved definition directly in the preview below; the simple Dimension/Measure fields underneath become irrelevant and are hidden. - **To author a new one** — leave BI View on "-- None --" and use the **"Author a new BI View"** section: pick a **Widget Type** (KPI Card, Chart, Table, or Pivot Table — see "Widget Type restrictions" below for when a type might be missing), check every **Dimension** and **Measure** you want included (you can select more than one of each — this is not limited to one-and-one), fill in a **View Code** and **View Name**, and click **"Save as new BI View."** On success it's automatically selected in the BI View dropdown above, ready to preview. 6. **Check the live preview.** As soon as a BI View is selected (existing or newly authored) and its query has real data, a "Preview" section renders the actual widget — you're looking at what will appear on a dashboard, not a mockup. For a **Pivot Table**, the preview runs in **design mode** — see "Working with a pivot table" below for what that means and what extra controls you'll see here that won't appear once the same view is placed on a live dashboard. 7. **(Field Mapping Review — ApiService-kind catalogs only.)** If the chosen catalog was built from an existing report, a **"Field Mapping Review"** section appears. Click **"Suggest field mappings from a live sample"** — this calls the real report once and proposes, for every field in its response, whether it looks like a Dimension or a Measure, its data type, and (for measures) a conservative default aggregation and additivity. Review each row — the suggestion is a starting point, not a final answer — edit the Label, whether it's mapped as Dimension or Measure, the default aggregation, and the additivity classification as needed, then click **Save** on each row you want kept. Once at least one field is saved, the Dimension/Measure pickers above will include it. 8. **(Optional) Cross-portlet Publish/Subscribe.** Below the preview, four optional text fields (Publish Channel, Publish Field, Subscribe Channel, Subscribe Field) let this widget participate in cross-portlet filtering on a dashboard — e.g. clicking a bar in this chart could filter another portlet on the same dashboard page. This is available for every portlet type, not just BI-backed ones. Leave all four blank if you don't need this — a channel and its matching field must be filled in together, or not at all (the screen will reject a half-filled pair on save). 9. **Click Save.** On success, you'll see a confirmation dialog and the form resets, ready for the next widget. The new Portlet now exists and can be placed onto any dashboard page through the normal "add portlet" flow, exactly like any other portlet type. ## Working with a pivot table Picking (or authoring) a **Pivot Table**-type BI View gives you a real, Excel-style crosstab — dimensions can be dragged onto a row axis or a column axis, measures subtotal correctly, and the whole thing behaves like a familiar spreadsheet pivot, not a flat grid. - **While authoring (this config screen's preview)**, the pivot's own toolbar shows the full set of authoring controls — fields, format, options, export, fullscreen — everything except local-file connect/open/save buttons, which never apply to a server-driven system like this one. Drag dimensions between the row and column axes to arrange the layout exactly how you want the final widget to look. - **Click "Save current layout"** once you're happy with the arrangement — this captures exactly which fields are on the row axis and which are on the column axis, and saves it onto the BI View. Do this *in addition to* the initial "Save as new BI View" step, if you've rearranged anything from its starting layout — the two are separate save actions. - **Once placed on a real dashboard**, the same pivot table renders in a more restricted "run" mode intended for end users — it additionally hides the format/options authoring controls (fields/export/fullscreen stay available), and it always shows the layout you last saved, not the view's original default arrangement. This is deliberate: an end user viewing a dashboard should be able to explore and export the data, not accidentally reformat someone else's saved widget. ## Widget Type restrictions Some Portlet Types are configured to only allow certain widget shapes (for example, a Portlet Type built specifically for KPI headline tiles might not offer Chart, Table, or Pivot Table at all). This is set once per Portlet Type by an implementation/dev team member, not per-widget — if you believe a widget type is missing that should be available, check with your implementation team about that Portlet Type's configuration rather than assuming the platform doesn't support it. ## Editing or deleting an existing portlet Pick it from the "Load Existing Portlet" dropdown at the top of the screen (lists every portlet by name and code, across all types, not just BI ones). The form populates with its saved configuration — for a BI-backed portlet, this includes re-selecting its BI View (or, for a portlet saved before BI Views existed, its legacy Dimension/Measure pair — see the Catalog for how that fallback behaves). Change what you need and click Save, or click **Delete** (only appears once an existing portlet is loaded) to remove it entirely. ## Common mistakes the screen will catch - **Leaving Portlet Type on "-- Select --" and clicking Save** — rejected with "Select a Portlet Type." - **Picking Analysis but not filling in a Dataset and either a Measure or a BI View** — rejected with "Select a Dataset and Measure for an Analysis portlet, or pick/create a BI View." - **Authoring a new BI View without checking at least one Dimension or Measure** — rejected with "Check at least one Dimension or Measure." - **Authoring a new BI View without a Widget Type, Code, or Name** — each is checked and rejected individually with a specific message. ## What this screen does *not* yet do - No way to filter a widget to a subset of data (e.g. "this year only," "this OU only") — see the Overview's "What's next." - No button to turn an existing report into a new catalog directly from this screen — the backend supports it, but today someone with API access has to create the catalog first; from then on, this screen's normal catalog picker sees it like any other. - No explicit chart sub-type override (bar vs. donut vs. line) in the config screen — the rendered chart sub-type is always auto-picked from the shape of the data.