Module Submission and Import

Module submission and import allows users to create, submit, share, and import modules from one instance of Ursa Studio to others. Modules are a collection of reports, measures, objects, terms, models, semantic mapping templates, value sets, and lookup tables that all share the same namespace. Each namespace will be maintained by Ursa or a particular customer, and the modules are by default private.

Ursa Library API Keys

Client implementations will automatically be registered into the Ursa Module Library via an access key with a tailored permission set. This access key should be set up as the URSA_LIBRARY_API_KEY environment variable. The tailored permission set allows read-only, write-only, or read-write access for each granted module.

Submitting Assets

Users can choose to submit any module for which their deployment has write-only or read-write access. Before submission, users will be able to see a preview of the assets to be submitted. Unlike in "Importing Assets", below, the entire set of assets within the module's namespace will be submitted at once; this is to ensure the integrity of the submitted module. Any piecemeal transfer of assets will be enforced on the import side, in which users can pick and choose among assets in the module.

Importing Assets

Users can choose to submit any module for which their deployment has read-only or read-write access. Before finalizing a module import, users will be able to see a preview of the assets to be imported and can remove assets from the import. The rules for overwriting existing assets with the same name and namespace (or, in the case of objects, the same table name) are dictated by the merge state of the asset, as described below. If an asset is overwritten during module import the previous version of the asset will be recoverable via the revision history.

Generally speaking, every field on an incoming asset will be carried into the target environment. For example, tags, field groups, and namespaces are all carried into the new environment, which means that these user-defined fields will be automatically and immediately created in the target environment if they are not already set up.

There are some exceptions to this--fields that are honored in the target (aka local or incumbent) environment--as follows. Incoming reports will automatically honor any local changes to the start and end dates, user list, "Add Viewing Access for All Users" setting, restriction level, and "Prevent Passive ELT" option. Incoming objects honor the "Prevent Passive ELT" and "Is Locked" options as well as the contents of the "Incremental Load", "Database Optimization", and "Object Backup" panels. Measures and models honor the "Is Locked" option. If an Integrator object is being overridden by an Integrator with “Clear Input Stacks for Module Submission” set up, the overwriting object will inherit the input stacks and mapping from the incumbent object.

Measure Objects are not included in the module import preview. These objects are added, edited, or removed based on the disposition of the measure that manages them.

During module import, reports with public boards will show each public board as a separately importable asset. Users are not allowed to import a board if they do not import the report. If the report already exists in the target environment, users can choose which, if any, boards to overwrite in the target environment. The user that performs the module import becomes the owner of the imported board.

Module Submission Prefix and Module Import Prefix

Module prefixes are a global variable meant to decollide module promotion workflows. If a customer wants to promote, for example, their URSA-CORE assets from a dev environment to a production environment, we want them to be able to do so without it colliding with the URSA-CORE assets that Ursa Health maintains in the Ursa Library. Within the Global Variables screen in Metadata Manager users should set their Module Submission Prefix in their dev environment to a unique code, and they should set their Module Import Prefix in the production environment to the same unique code. This will create an alternate naming convention for the Ursa Library, while otherwise being mostly invisible to the app.

Module History

The Module History tab within the Integration Manager dashboard shows the name, timestamp, status, and optional comment of the last 50 module imports or submissions.

SQL Diff View

Users with SQL visibility privileges will be able to see a SQL diff representation of all the updates of all objects during module import via a link at the top of the module import screen.

Merge States

Ursa Studio keeps track of changes to both the module definition of all assets, as well as the local version of those assets. For example, after being imported, an asset may or may not be localized. And, after being imported, the module version of that asset might have been updated. It's possible that both have happened. Thus, the four possible "Merge States" as displayed on the module import screen are, "All Matching", "Local Edits", "Updated Module", and "Branching Edits".

Depending on where the changes have been, the rules for including an asset as part of a module import will be different. For example, if neither the local version nor the module version has changed, then the asset will always skip being imported, because nothing would change. If the local version has changed (i.e., "Local Edits" or "Branching Edits"), the default will be to skip the import, though users dealing with "Branching Edits" assets would be well served to manually determine the nature of the edits and possibly pull in the updated module assets.

In the cases where an incoming asset honors the existing localized change to the incumbent asset, a change to a non-overwriting part of an asset will not be considered a change to the asset for the purposes of determining the merge state. Ad-hoc derived fields in measures do get overwritten upon re-import of a measure, so changes to these fields are considered a change to the asset.

All assets except value sets and lookup tables will consider as "All Matching" any change that was independently but exactly updated on both the local and the module version of the asset.