Cordex-Reference Admin Guide

Overview

Cordex Reference brings the Cordex Terminology API into Dataverse as read-only virtual tables: clinical terminologies (SNOMED CT-AU, LOINC, ICD-11, CDC code sets, the Australian National Notifiable Disease List) and reference data (addresses, countries, states, time zones, languages, currencies, units, elements and the GBIF taxonomy of plants, animals and other organisms). Users see the tables like any other table: views, forms, Quick Find, Advanced find and lookups from your own tables.

• No data is copied into Dataverse. Each query goes to Cordex at the moment it runs, so users always see the current approved release.
• The solution is free. Access to data comes from Cordex Terminology licence keys, one per plan (Clinical, Geography, People, Commerce, Science, Enterprise).
• Licence keys decide which tables return data. All tables are installed; a table without a covering key says so instead of returning rows.
• Administration happens on the Cordex Reference Administration page: Licences, Tables, Variants, Filters and Views.
• Cordex Developer under Guides in the app opens the Cordex Terminology developer site (cordexapps.com/cordex-terminology/developer/) in a new browser tab.
• Every table name starts with Cordex (for example Cordex Currency), so users can tell Cordex tables from standard and other custom tables.
• Cordex Terms under Guides in the app opens the Cordex Reference terms in a new browser tab.
• Terms and support: use of Cordex Reference is governed by the Cordex Reference terms; the datasets by the Cordex Terminology terms and data licences. Support is by email to cordex-reference@myitandapps.com.au and covers the solution as supplied, not your environment or customisations.

Before you start

• The role Cordex Reference Administrator, System Customizer or System Administrator for licences, table status and permanent filters (see Give users access). Variants, views and new columns change tables, views and forms, so they need System Customizer or System Administrator, in development.
• A Cordex Terminology licence key for each plan you bought (format KW-XXXX-XXXX-XXXX-XXXX). Your Cordex agreement decides which environments a key may be used in.
• Dataverse reaches Cordex from Microsoft's servers over HTTPS (https://api.cordexapps.com). There is nothing to configure on your network.
• The model-driven app that holds Cordex Reference, with the Cordex Reference Administration page in its site map.

Datasets and tables

Cordex Reference installs one virtual table per Cordex dataset. Address (AU) has two tables: Address Area (postcode and locality roll-ups) and Address (every geocoded G-NAF address).

Every Codes table has the same core columns: Id (key), Code, Source Entity Id, Entity Uri, Display (name), Definition, Status, Parent Code, Parent Id, Hierarchy Path, System and Release, followed by the dataset's own columns. The Science plan also covers Unit. Enterprise covers every dataset.

In the Cordex-Reference app the tables are grouped by API family (Clinical, Commerce, Geography, People, Science) and listed alphabetically. Each table opens on its Active view (rows with Status active); the All view shows every row. The main form shows the core columns under General and the dataset's own columns under Details. Address (AU) has no Status column and opens on its All view.

Licences

Add a licence

1. Open Cordex Reference Administration, tab Licences.
2. Paste the key into Licence key. Optionally give it a name, for example Clinical production.
3. Select Add and validate. Saving checks the key with Cordex (up to a minute) and binds it to every table it covers.

The list shows only the last four characters of each key. The key itself is stored only in a secured column of the licence; the provider reads it on the server, and it never reaches a browser.

Licence status

Several keys

An environment can hold one key per plan. When more than one valid key covers a dataset, each table uses exactly one key, chosen in this order:

1. the key that covers the most datasets (an Enterprise key covers every dataset, so it outranks any single-plan key);
2. then the key with the latest expiry (a key with no expiry counts as latest);
3. then the key added first.

All users of a table share its key's rate limit: 1,200 calls per minute per plan key, 6,000 for Enterprise.

Validate, renew and remove

• Validate on a row, or Validate all, checks keys with Cordex again and binds every table. Do this after a renewal or a plan change.
• Remove deletes the licence and binds the tables again without it. Tables only it covered show No licence.
• Adding a key that already exists is refused with the name of the row that holds it.

Table status

Give users access

Cordex Reference ships two security roles. Assign them with a role that lets users run model-driven apps, such as Basic User.

The administration page and the Admin and Ops guides appear in the app menu only for users who can read the Cordex licence table. A user without that access who opens the page sees which roles open it.

System Customizer: the setup checks whether this Microsoft role holds what the administration page needs in your environment. If a System Customizer does not see Reference Admin, assign Cordex Reference Administrator as well.

Assign a role

1. Sign in to the Power Platform admin center as a System Administrator.
2. Manage, Environments, select the environment, Settings.
3. Users + permissions, Users, select the user, Manage security roles.
4. Tick Cordex Reference User (and Cordex Reference Administrator for administrators) and Basic User. Select Save.

You can assign the roles to a team instead of each user.

Sources: Microsoft Learn, Assign a security role to a user; Secure your custom API by requiring a privilege.

Permanent table filters

A permanent filter limits a table for everyone, everywhere: views, Quick Find, lookups, forms and the API. It is sent to Cordex with every query, so rows outside it never leave Cordex. This keeps lists short and reduces calls against your rate limit.

Set a filter

1. Tab Filters, choose the table or variant in Table (or select it in the list of tables with a permanent filter). It must show Licensed.
2. In the Builder, select Add condition and choose a column, an operator (Equals, Contains, Begins with, Is one of, Has a value and so on) and a value. Tick Ignore case to match text in any case. With two or more conditions, choose whether rows must match all of them (and) or any of them (or).
3. The line under the builder shows the exact filter sent to Cordex. For anything the builder cannot express (brackets that mix and with or, or functions such as length), switch to OData text; select a column chip to insert its exact name. A saved filter opens in the builder when the builder can show it exactly, otherwise as OData text.
4. Test runs the filter at Cordex, reports how many rows match and shows the first 20 of them in a grid (the table's name, Code and Status columns first, then up to nine more). Save tests again and stores it. Remove filter returns the table to the whole dataset.

Filter syntax (OData text)

The builder writes these forms for you. Column names are the Cordex property names and are case-sensitive (Country, not country). Text values go in single quotes; double a quote inside a value ('O''Brien').

Taxonomy and kingdoms. Taxonomy (GBIF) is one dataset for every kingdom. The nine kingdom tables (Animalia, Plantae, Fungi, Chromista, Protozoa, Bacteria, Archaea, Viruses and incertae sedis) are the same dataset with a built-in filter such as Kingdom eq 'Plantae' (flora) or Kingdom eq 'Animalia' (fauna). The built-in filter cannot be removed; a permanent filter you save on a kingdom table is added to it, and the Filters tab shows both.

Also available: or, brackets, toupper, trim, length, indexof, substring and concat. A filter is one line of at most 2,000 characters.

Variant tables

A variant is a copy of a Cordex table with its own permanent filter, for example Cordex Subdivision NZ beside Cordex Subdivision. It uses the same dataset and the same licence key as the table it copies.

1. In your development environment open Cordex Reference Administration, tab Variants, card New variant table.
2. Enter a Table name, for example Subdivision NZ. The page shows what it will create: the table Cordex Subdivision NZ with logical name mitaa_subdivisionnz (mitaa_ followed by the name in lowercase letters and digits; spaces and other characters are left out).
3. Choose the Cordex table to copy (Copy of) and your own unmanaged Solution.
4. Select Create variant and confirm. The page creates the Cordex data source record, the virtual table with the copied table's settings and icon, every mapped column, the All and Active views, the system views and the main form, publishes the table and binds your licence (Validate all). Each step is listed as it completes. A copy of a kingdom table (for example Animalia) keeps the kingdom's filter: the page saves it as the variant's permanent filter.
5. The page then opens the Filters tab on the new variant. Build its permanent filter there, for example Country, Equals, NZ (see Permanent table filters).
6. Add the variant to your own app and its site map. Do not add it to the Cordex-Reference app: that app is part of the managed Cordex solution.
7. Export your solution as managed and import it into test, UAT and production after Cordex-Reference (see Moving changes between environments).

If a step fails, the page stops and lists what it created. Delete those parts from your solution before trying again with the same name.

In test, UAT and production there is nothing to do. The variant arrives with your managed solution, and Cordex Reference finds it because its data source record points at the same Cordex dataset as the table it copies. It is bound to your licence the next time anyone runs Validate all, or by itself when a System Administrator opens any tab of the administration page other than Licences.

The Variants tab lists every variant with the table it copies, its status and licence. Its filter is on the Filters tab and its columns on the Tables tab, as for any Cordex table. To remove a variant, see Remove a variant, filter or view.

Columns from Cordex

Cordex can add properties to a dataset in a new release. Cordex Reference never adds columns by itself; a System Administrator adds the ones wanted, in development.

1. Tab Tables, select the table (a Cordex table or a variant). It must show Licensed.
2. Card Columns from Cordex, select Check Cordex properties. The page lists every property Cordex serves now that has no column on the table, with the column it would create: logical name mitaa_ plus the property name in lowercase, label from the property name.
3. Tick the properties to add, choose your Solution and select Add selected columns.
4. The page creates the columns (text up to 4,000 characters, whole number, floating point number or Yes/No, by Cordex type), adds them to the main form's Details section and to the All view, and publishes the table. A field it cannot place on the form (no field of the same type there to copy) is named in the step list; add that one in the form designer.

Remove a variant, filter or view

Variant

1. Remove the variant from your own app's site map and app components, and publish the app. Dataverse will not delete a table an app still uses.
2. Tab Variants, Delete on the variant, confirm. The page deletes the table with its views and forms, its Cordex data source record and its Cordex table status row.

A variant whose table was deleted in the maker portal stays in the list as Not installed, because its status row remains. Select Remove leftover to delete that row and any data source record left behind.

Permanent filter

Tab Filters, choose the table, Remove filter, confirm. The table shows the whole dataset again (a kingdom table keeps its built-in filter).

View

Tab Views, choose the table. Views of the table lists its public views; Delete a view and confirm. The page publishes the table. The default view and managed views have no Delete; make another view the default in the view designer first if you want to delete it.

Views and searching

Views tab

1. Tab Views, choose a Licensed table, name the view and choose your unmanaged Solution.
2. The column list starts with the columns, widths and sort of the table's default view. Add column adds more; Remove takes one out; drag a row, or choose its Position, to change the order; type a Width in pixels (50 to 1,000). The line under the list summarises the columns in order.
3. Add conditions (all must match) and choose a sort.
4. Create and publish view and confirm. The view is checked before it is saved: the provider must translate it and Cordex must accept it within the table's permanent filter. The message reports how many rows match. Refresh the app (Ctrl+F5) to see the view.

Column headings come from each column's display name. The Cordex-Reference app shows every view of each table, so a new view needs no change to the app.

Supported conditions

Equals and Is one of compare exactly. Contains, Begins with and Ends with ignore case. The same rules apply to views built in the standard view editor and to Advanced find.

Quick Find and lookups

• Quick Find searches the columns in the table's Quick Find view and matches from the start of the value (coronavirus finds Coronavirus disease (COVID-19)). Start with an asterisk to search anywhere in the value (*covid).
• Lookups from your own tables to a Cordex table work (many-to-one). The Cordex Id of a row never changes between releases, so a lookup stays valid when Cordex publishes a new release. Also store the code and display as text on your record if you need them for history.

Not supported

• Joins from a Cordex query to other tables, aggregate queries, date conditions, the _ wildcard and a % in the middle of a pattern.
• Microsoft limits virtual tables: no Dataverse search, charts, dashboards, auditing, column security or change tracking on the virtual tables themselves.
• The tables are read only.

Moving changes between environments

Build every change in development and move it to test, UAT and production as a managed solution. Changes made directly in test, UAT or production sit in the unmanaged layer. Microsoft describes it as the top layer of a component, the one that decides how the component behaves, so it masks what later managed imports bring.

What moves in a solution, and what does not

Release steps

1. Development: make the change in your unmanaged solution (variants, views, your app). Test it.
2. Export your solution as managed. Keep the unmanaged export as your source.
3. Test, then UAT, then production: install or upgrade Cordex Reference first if its version changed, then import your managed solution.
4. In each environment: Licences tab, Validate all. Check that your tables show Licensed and that the views appear.

Importing Cordex Reference can report Data Source secrets are not included in solutions (0x80044818), once for each Cordex data source record, each marked Processed. This is expected and needs no action: Cordex Reference stores no secrets on data source records.

Avoid and remove unmanaged layers

• Do not use the Views tab, the New variant table card, Columns from Cordex or the app designer on Cordex components in test, UAT or production. The page warns before every change.
• To check a component: Power Apps, Solutions, open the solution, select the component, Advanced, See solution layers. An Unmanaged layer entry means someone changed it in that environment.
• To remove it: select that layer and Remove active customizations. Microsoft warns this cannot be undone; the component then behaves as the managed solutions define it.
• Upgrading from Cordex Reference 1.0.0.3 or earlier: those versions wrote licence keys and filters onto the Cordex data source records, which left an unmanaged layer on each one in test, UAT and production. After upgrading, remove that layer from every Cordex data source record (Remove active customizations), or uninstall Cordex Reference and install the new version. Then run Validate all. Filters you saved stay: they were also kept on the tables' status rows.
• Production guard: in the Power Platform admin center, the environment's Features settings include Block unmanaged customizations. It blocks unmanaged imports, new components and unmanaged changes to managed components, while still allowing removal of unmanaged layers. Read Microsoft's list of features it affects before you turn it on.

Sources: Microsoft Learn, Solution layers and Block unmanaged customizations.

Security

• Licence keys are stored in the Cordex Licence table in a secured column. No Cordex role can read it. Administrators add keys through the Custom API mitaa_AddCordexLicence, which writes the key on the server; the page then shows only the last four characters.
• Every Cordex Custom API requires a privilege on the licence or status table, so users without an administrator role are refused before any code runs. The plug-ins act as the caller, so the caller's own role decides what may change; only the key column is read or written as the system.
• Each table's status row records which licence covers it; the provider reads that licence's key on the server. Cordex data source records are never written after installation, so licences and filters make no unmanaged changes.
• The role Cordex Reference User gives Read on the Cordex tables and their data source records only; Cordex Reference Administrator adds the licence and status tables. The provider reads the licence and status rows on the server as the system, so users need no access to them.
• Pages and scripts in the browser never receive a key. The Administration page calls Custom APIs that run on the server.
• Plug-in trace lines record whether a key was passed and its length, never the key.
• Calls to Cordex use HTTPS and carry the key in the X-Cordex-Client-Key header.

Messages and what to do

More detail for each message is in the plug-in trace log (Ops Guide, Monitoring).

Data sources and licences

Cordex Reference stores no reference data in Dataverse. Every row is read from the Cordex Terminology API when a user opens a view, form or lookup. Each dataset stays under its publisher's licence, and your organisation must meet those terms when it uses or displays the data.

Terms