Linked schemas are especially useful when you want to reveal some data in a folder without granting access to the whole folder. For example, suppose you have the following data in a single folder A. Some data is intended to be private, some is intended for the general public, and some is intended for specific audiences:
The nature of a linked schema is to provide access to tables and queries in another folder which likely has different permissions than the current folder.
Permissions: A linked schema always grants the standard "Reader" role in the target folder to every user who can access the schema. Site Administrators who configure a linked schema must be extremely careful, since they are effectively bypassing folder and dataset security for the tables/queries that are linked. In addition, since the "Reader" role is granted in only the target folder itself, a linked schema can't be used to execute a "cross-container" query, a custom query that references other folders. If multiple containers must be accessed then multiple linked schemas will need to be configured or an alternative mechanism such as an ETL will need to be employed. Linked schemas also can't be used to access data that is protected with PHI annotations.
Lookup behavior: Lookups are removed from the source tables and queries when they are exposed in the linked schema. This prevents traversing a table in a linked schema beyond what has been explicitly allowed by the linked schema creator.
URLs: URLs are also removed from the source tables. The insert, update, and delete URLs are removed because the linked schema is considered read-only. The details URL and URL properties on columns are removed because the URL would rarely work in the linked schema container. If desired, the lookups and URLs can be added back in the linked schema metadata xml. To carry over any attachment field links in the source table, first copy the metadata that enables the links in the source table and paste it into the analogous field in the linked schema table. See below for an example.
A user must have the "Site Administrator" role to create a linked schema.
To create a linked schema in folder B that reveals data from folder A:
You can add metadata xml that filters the data or modifies how it is displayed on the page.
In the following example, a filter is applied to the table Location such that a record is shown only when InUse is true.
<tables xmlns="http://labkey.org/data/xml" xmlns:cv="http://labkey.org/data/xml/queryCustomView">
<filters name="public-filter">
<cv:filter column="InUse" operator="eq" value="true"/>
</filters>
<table tableName="Location" tableDbType="NOT_IN_DB">
<filters ref="public-filter"/>
</table>
</tables>
Attachment fields in the source table are not automatically carried over into the target schema, but you can activate attachment fields by providing a metadata override. For example, the XML below activates an attachment field called "AttachedDoc" in the list called "SourceList", which is in the domain/folder called "/labkey/SourceFolder". The URL must contain the listId (shown here = 1), the entityId, and the name of the file.
<tables xmlns="http://labkey.org/data/xml">
<table tableName="SourceList" tableDbType="NOT_IN_DB">
<columns>
<column columnName="AttachedDoc">
<url>/labkey/SourceFolder/list-download.view?listId=1&entityId=${EntityId}&name=${AttachedDoc}</url>
</column>
</columns>
</table>
</tables>
The entityId is a hidden field that you can expose on the original list. To see it, open (Grid Views) > Customize Grid, then check the box for "Show Hidden Fields" and scroll to locate the checkbox for adding "Entity Id" to your grid. Click View Grid to see it. To include it in the URL carried to the target schema, use the syntax "${EntityId} as shown above.
For more information about metadata xml, see Query Metadata.
Default values can be saved as a "schema template" -- by overriding parts of the template, you can change:
myModuleA/resources/schemas/ClientA.template.xml
The example .template.xml file below provides a default linked schema and a default filter xml for Client A:
ClientA.template.xml
<templateSchema xmlns="http://labkey.org/data/xml/externalSchema"
xmlns:dat="http://labkey.org/data/xml"
xmlns:cv="http://labkey.org/data/xml/queryCustomView"
sourceSchemaName="assay.General.Custom Assay">
<tables>
<tableName>Data</tableName>
</tables>
<metadata>
<dat:tables>
<dat:filters name="client-filter">
<cv:filter column="Client" operator="eq" value="A Client"/>
</dat:filters>
<dat:table tableName="Data" tableDbType="NOT_IN_DB">
<dat:filters ref="client-filter"/>
</dat:table>
</dat:tables>
</metadata>
</templateSchema>
You can override any of the template values by clicking Override template value for the appropriate region.
For example, you can create a schema for Client B by (1) creating a new linked schema based on the template for Client A and (2) overriding the metadata xml, as shown below:
Once you've clicked override, the link will change to read Revert to template value giving you that option.
Linked schemas will be evaluated with the permissions of the user who originally created them. If that user is later deleted from the system, or their permissions change, the schema may no longer work correctly. Symptoms may be errors in queries, the disappearance of the linked schema from the schema browser (while it still appears on the schema administration page) and other issues.
There are two ways to fix this:
| previousnext |
| expand allcollapse all |
