Cordex-Reference Ops Guide

Overview

This guide is for the people who run Cordex Reference in your environments: platform administrators and support. It covers what is installed, how to watch it, routine tasks, incidents and removal. Day-to-day administration (licences, filters, views) is in the Admin Guide.

Cordex Reference is a custom virtual table data provider. When Dataverse needs rows from a Cordex table, the provider plug-in reads the table's data source record (service root) and, as the system, its status row and licence (key, permanent filter), translates the Dataverse query into an OData query, calls the Cordex Terminology API and returns the rows. Nothing is cached in Dataverse except the table definitions (10 minutes) and each dataset's column list (10 minutes).

Installed components

How a query runs

1. A user opens a view, Quick Find, form or lookup on a Cordex table.
2. Dataverse runs RetrievePlugin (one record) or RetrieveMultiplePlugin (a list) and gives it the table's data source record.
3. The plug-in refuses the call if the record has no key ("not licensed") or carries another environment's id ("this environment is a copy").
4. It reads the table definition and maps each column to its Cordex property (External Name), checks columns against the dataset's current column list, and builds $select, $filter (permanent filter AND the query's filter), $orderby, $top, $skip and $count.
5. It calls Cordex over HTTPS with a 20 second timeout and returns the page (up to 5,000 rows per page).

Licence work runs separately: saving, deleting or validating a key calls Cordex once for the plan and once per dataset (up to 100 seconds), stores the result and binds every table.

Monitoring and diagnostics

Plug-in trace log

1. Settings, Administration, System Settings, Customization, Enable logging to plug-in trace log: All while investigating, Exception otherwise.
2. Settings, Plug-in Trace Log. Filter Type Name starting with CordexReference.Plugins.

Health checks

• Cordex Reference Administration, Licences: every licence Valid, last validated recent, expiry not close.
• Tables tab: the tables you use show Licensed; none show Data source shared.
• Trace log: 429 statuses show the key's rate limit is being reached; 5xx or timeouts point to Cordex or the network.
• Cordex returns the release that answered every call; the Release column on each row shows the same.

Routine tasks

Renew or rotate a key

1. Licences tab, add the new key (the old one stays bound meanwhile).
2. Confirm the new key is Valid and tables show it on the Tables tab.
3. Remove the old licence.

Plan change at Cordex

Validate all. Tables move to Licensed or Not in plan to match the new plan.

Revalidation

Validate all after any renewal or plan change, and at least monthly, so expiry and plan stay current. Validation only reads from Cordex and rewrites the bindings; it is safe to run at any time.

Change a permanent filter

Filters tab, choose the table, Test, then Save. The change applies to the next query; there is nothing to publish.

Add a Cordex table to your own app

In development, add the table to your own app in your own solution; the Cordex-Reference app is part of the managed Cordex solution and is not edited. Each Cordex table opens on its Active view, so users do not page through whole datasets. Move the app on as a managed solution (Admin Guide, Moving changes between environments).

Environment copies and restores

A copied or restored environment carries the source environment's licences and bound keys. To stop a UAT copy from silently using production's key, every licence records the environment id it was validated in, and the provider refuses calls from a different environment until the licence is validated there.

1. After the copy, users of Cordex tables see "This environment is a copy: its Cordex licence was validated in another environment."
2. A Cordex Reference administrator opens Cordex Reference Administration in the copy and either removes the source environment's licences and adds the keys meant for this environment, or selects Validate all to use the same keys here.
3. Validation stamps the new environment id and binds the tables. Check your Cordex agreement before reusing a key from another environment; replace it with this environment's own key where required.

Incidents

All Cordex tables fail

• Trace shows timeouts, "could not be reached" or 5xx: Cordex or network outage. Licences stay Valid; nothing to change. Retry later.
• Trace shows 401 or 403 with client_key_*: the key was revoked or expired. Validate all to update statuses; renew or replace the key.
• "This environment is a copy": see Environment copies.

One table fails

• Status Not in plan or No licence: add a key that covers it.
• Status Not published: the dataset is not released yet.
• Status Data source shared: give each table its own data source record.
• "Column ... is not in the current Cordex release": remove that column from the filter or sort of the failing view.
• HTTP 400 bad_filter: the permanent filter or a view condition is invalid; Test the filter on the admin page.

Rate limiting (429)

All users of a key share its limit. Reduce calls: filter default views, set permanent filters, avoid views that page through whole datasets, and consider an Enterprise key (6,000 calls per minute).

Message reference

Removing Cordex Reference

1. Remove every licence on the Licences tab. Every table then reports No licence.
2. Remove your own lookups to Cordex tables, and your own views, forms and app references to them.
3. Uninstall your own solutions that hold variant tables, views or apps built on Cordex tables. In development, delete the variant tables and their Cordex data source records from your unmanaged solution.
4. Uninstall the solution.

Limits

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.