Editing Migration Package Template Files

If a Variable Template File and/or Access Control Template File is included in a Migration Package export, the files must be edited to replace all of the placeholder values before the package can be imported to the target server. This topic describes the template files and provides guidance on editing the templates.

Editing a Variable Template File

A Variable Template File is a TriG file that is used to define the values to use in Replaceable Statements. Properties with replaceable values are objects such as File Connection paths, Anzo Data Store locations, File-Backed Linked Data Set locations, and file locations for file-based Data Sources, which might differ on the source and target Anzo servers. The template that is generated has placeholder text that you replace with the desired values for the target server. The values that you specify are applied to all artifacts included the Migration Package.

When you open a Variable Template File, the placeholder values are denoted by three hash characters (###) and all capital letters, for example, ###FILEPATH-1###. The example below shows a snippet of a Variable Template File. The placeholder text is shown in bold:

<http://openanzo.org/ReplacementObject/10441bd7-03fb-494a-b56a-cc0eea32aed2> {
  <http://cambridgesemantics.com/PathConnection/6bd218a15c644045ba43f007c824d830> <http://cambridgesemantics.com/ontologies/DataSources#filePath> "###FILEPATH-2###" .

  <http://openanzo.org/ReplacementObject/10441bd7-03fb-494a-b56a-cc0eea32aed2> a <http://cambridgesemantics.com/ontologies/2021/06/Migration#ReplacementObject> ;
    <http://cambridgesemantics.com/ontologies/2021/06/Migration#forGraph> <http://cambridgesemantics.com/CSVDataSource/f9a54e23d83549999536782b5de1981c> .
}

<http://openanzo.org/ReplacementObject/1c79ae8a-c570-4170-a9f8-f1a5dd967c6d> {
  <http://csi.com/DataLocation/157ae35ecab30f803c754d314be18e44> <http://cambridgesemantics.com/ontologies/DataSources#filePath> "###FILEPATH-9###" .
  
  <http://openanzo.org/ReplacementObject/1c79ae8a-c570-4170-a9f8-f1a5dd967c6d> a <http://cambridgesemantics.com/ontologies/2021/06/Migration#ReplacementObject> ;
    <http://cambridgesemantics.com/ontologies/2021/06/Migration#forGraph> <http://csi.com/FileBasedLinkedDataSet/157ae35ecab30f803c754d314be18e44> .
}

<http://openanzo.org/ReplacementObject/21f24dda-fba6-47d7-bb6d-90e1fafec623> {
  <http://csi.com/DataLocation/7214e9ec270347dabeccbfc7328b4bed> <http://cambridgesemantics.com/ontologies/DataSources#filePath> "###FILEPATH-7###" .

  <http://openanzo.org/ReplacementObject/21f24dda-fba6-47d7-bb6d-90e1fafec623> a <http://cambridgesemantics.com/ontologies/2021/06/Migration#ReplacementObject> ;
    <http://cambridgesemantics.com/ontologies/2021/06/Migration#forGraph> <http://csi.com/FileBasedLinkedDataSet/7214e9ec270347dabeccbfc7328b4bed> .
}

When replacing the placeholder text, edit the text inside the quotation marks. All objects should retain the quotes. If the replacement value is a URI, place the URI inside the quotation marks.

Editing an Access Control Template File

The Access Control Template is a TriG file that is used to define the permissions to be assigned on all artifacts included in the Migration Package. The template contains two sets of statements, one set for the artifact graphs (<http://openanzo.org/namedGraphs/reserved/graphs/defaultGraphTemplate>) and one for the artifact metadata graphs (<http://openanzo.org/namedGraphs/reserved/graphs/defaultMetadataGraphTemplate>). The objects in the template are placeholder URIs that must be replaced with the Group and/or User URIs on the target server. A copy of the template is shown below. The placeholder URIs are shown in bold:

<http://openanzo.org/namedGraphs/AclTemplate> {
  <http://openanzo.org/namedGraphs/reserved/graphs/defaultGraphTemplate> <http://openanzo.org/ontologies/2008/07/Anzo#canBeAddedToBy> <urn://ACL-ADD-ROLE-PLACEHOLDER> ;
    <http://openanzo.org/ontologies/2008/07/Anzo#canBeReadBy> <urn://ACL-READ-ROLE-PLACEHOLDER> ;
    <http://openanzo.org/ontologies/2008/07/Anzo#canBeRemovedFromBy> <urn://ACL-REMOVE-ROLE-PLACEHOLDER> .
 
  <http://openanzo.org/namedGraphs/reserved/graphs/defaultMetadataGraphTemplate> <http://openanzo.org/ontologies/2008/07/Anzo#canBeAddedToBy> <urn://ACL-METAADD-ROLE-PLACEHOLDER> ;
    <http://openanzo.org/ontologies/2008/07/Anzo#canBeReadBy> <urn://ACL-METAREAD-ROLE-PLACEHOLDER> ;
    <http://openanzo.org/ontologies/2008/07/Anzo#canBeRemovedFromBy> <urn://ACL-METAREMOVE-ROLE-PLACEHOLDER> .
}

The defaultGraphTemplate statements configure who can view, modify, and delete the artifact. The defaultMetadataGraphTemplate statements configure who can view, modify, and delete artifact metadata, such as an artifact's permissions. The list below describes how the template properties map to permissions:

canBeReadBy

This property assigns View and Meta View permissions. On the defaultGraphTemplate, this property assigns View, which grants access to see the artifact but not change it. On the defaultMetadataGraphTemplate, this property assigns Meta View, which grants access to see the artifact's permissions but not change them.

canBeAddedToBy

This property assigns Add/Edit and Meta Add/Edit permissions. On the defaultGraphTemplate, this property assigns Add/Edit, which grants permission to change the artifact or add an entity to it, such as to add a Schema to a Data Source. On the defaultMetadataGraphTemplate, this property assigns Meta Add/Edit, which grants permission to change the artifact's permissions.

canBeRemovedFromBy

This property assigns Delete and Meta Delete permissions. On the defaultGraphTemplate, this property assigns Delete, which grants permission to delete an entity from an artifact, such as to delete a Data Layer from a Graphmart. On the defaultMetadataGraphTemplate, this property assigns Meta Delete, which grants permission to delete the parent artifact and change the artifact's permissions.

For more information about artifact permissions, see Permission Settings.

Finding Group and User URIs

In order to complete the Access Control Template and give groups access to the artifacts in the package, you need to find the Group and/or User URIs on the target server to add as objects to the template properties (canBeReadBy, canBeAddedToBy, and canBeRemovedFromBy).

  1. If you need to review a list of the Groups that are available on the target system, open the Administration application on that server. To access the Group names, expand the User Management menu and click Groups. For example:

  2. Note the names of the Groups whose URIs you want to add to the template.
  3. Next, find the URIs for the Group names. In the Anzo application on the target server, expand the Access menu and click Query Builder. Anzo displays the Query tab. Click the Find tab.

  4. On the Find tab, leave the datasource set to System Datasource and then type a Group Name in the Object field. For example:

  5. Next, click the Find button. The result is a statement that defines that Group. The value in the Subject position is the URI for the Group. For example:

  6. Click the URI to add it to the Subject field at the top of the screen, and then copy the URI from that field. For example, the URI copied from the image above is <ldap:///cn=data%20onboarders,ou=groups,dc=acme,dc=com>.

Repeat the steps above to find all of the URIs that you want to add to the template. To add URIs to the file, replace each of the placeholder URIs. You can add multiple URIs to a property in a comma-separated list. For example:

<http://openanzo.org/namedGraphs/AclTemplate> {
  <http://openanzo.org/namedGraphs/reserved/graphs/defaultGraphTemplate> <http://openanzo.org/ontologies/2008/07/Anzo#canBeAddedToBy>
        <ldap:///cn=data%20onboarders,ou=groups,dc=acme,dc=com>, <ldap:///cn=graphmart%20creator,ou=groups,dc=acme,dc=com>, <ldap:///cn=graphmart%20user,ou=groups,dc=acme,dc=com>  ;
    <http://openanzo.org/ontologies/2008/07/Anzo#canBeReadBy> <ldap:///cn=graphmart%20user,ou=groups,dc=acme,dc=com> ;
    <http://openanzo.org/ontologies/2008/07/Anzo#canBeRemovedFromBy> <ldap:///cn=administrator,ou=groups,dc=acme,dc=com> .
 
  <http://openanzo.org/namedGraphs/reserved/graphs/defaultMetadataGraphTemplate> <http://openanzo.org/ontologies/2008/07/Anzo#canBeAddedToBy> <ldap:///cn=data%20onboarders,ou=groups,dc=acme,dc=com> ;
    <http://openanzo.org/ontologies/2008/07/Anzo#canBeReadBy> <ldap:///cn=graphmart%20user,ou=groups,dc=acme,dc=com> ;
    <http://openanzo.org/ontologies/2008/07/Anzo#canBeRemovedFromBy> <ldap:///cn=administrator,ou=groups,dc=acme,dc=com> .
}

Related Topics