Add a Custom Profile
This topic describes how the geoportal web application supports its default metadata profiles, and how it can be configured to support additional metadata profiles. First, we will discuss the process of how a discoverable metadata document is created and published to the geoportal. Then, we will describe the profile customization process step by step. TIP: Reading Details of Lucene Indexing in the Geoportal before or after this topic is recommended.
|
Before you customize the geoportal schema files to create a custom profile, first it is necessary to understand what happens behind the scenes to create a discoverable metadata document. Most of the files used to define the metadata profiles and how they are indexed for searching are located in the \\geoportal\WEB-INF\classes\gpt\metadata folder of the geoportal web application. Files that pertain to a specific profile are found in subfolders organized by the name of the profile which they support (e.g., files defining the ISO-based profiles are in the iso subfolder, files defining the fgdc profile are in the fgdc subfolder, etc.). The steps and graphic below provide an overview of how these files work together with the user workflow to create a metadata document.
- A publisher user logs in to the geoportal, clicks the Administration tab in the geoportal interface, clicks the Add link on the Manage Resources page, and the selects the Use dedicated editor to create metadata manually radio button.
- The Create Metadata page loads, reading the available metadata profiles from a file called schemas.xml and displaying them for the publisher to choose.
- The publisher chooses one of the profiles from the list.
- The geoportal loads the metadata editor form that corresponds to that profile. The fields of the form are defined by that profile's definition.xml file. The defintion.xml file will either define the supported fields in the form, or provide a link to the Geoportal XML Editor (GXE) files that will define these fields. In either case, string values for the form interface are referenced from the gpt.properties file.
- The publisher inputs information about the resource he/she is describing into the form, and clicks the Save button.
- Upon saving, the geoportal validates that all parameters that are designated as mandatory have been filled out in the form. If the definition.xml file contains an xsd reference, the geoportal also validates that the information satisfies the requirements of the xsd. If the document passes these validations, then the geoportal writes the metadata content into a metadata XML document. If the definition file did not use the GXE method to generate the form, then the metadata entered in the form is written using a template, which comes from the template.xml file for that profile. The metadata XML document is stored in the local geoportal catalog.
- When an administrator approves the resource, the geoportal indexes the content of the metadata XML for search using the Lucene index. The geoportal uses that profile's indexables.xml file to define which elements should be indexed, and the property-meanings.xml file to define how those elements should be indexed.
- When users search the geoportal for approved metadata content, the geoportal uses the Lucene index to look up indexed search terms from the metadata XML. The matching documents are retrieved from the geoportal catalog.
In the process shown above, several files were identified that were important for creating a discoverable metadata document. There is an additional file that is also important called sample-schema.xml. The locations and basic descriptions of these files are listed below.
| File name | Description | Location |
|---|---|---|
| sample-schema.xml | Defines the terms and schema for the definition.xml file. Tip: use this file as a reference when creating or altering a definition.xml file. | \\geoportal\WEB-INF\classes\gpt\metadata |
| schemas.xml | Defines the list of available profiles the publisher user can choose from on the Create Metadata page. There is only one schemas.xml file, which contains references to each available standard. | \\geoportal\WEB-INF\classes\gpt\metadata |
| template.xml* | A metadata XML file that follows the structure of the standard, but is not populated with values. It is a template that the geoportal will populate with information the user enters in the online form. | \\geoportal\WEB-INF\classes\gpt\metadata\<profile> |
| definition.xml* | Can point to the GXE method for defining the form, or defines the elements and their appearance on the online form itself (in which case, it also directs the geoportal how to map information from the form to the template metadata document). This file also defines the interrogation rules to identify if a document conforms to this profile. If an xslt is not used to render the Details page, this file will be used to render it. | \\geoportal\WEB-INF\classes\gpt\metadata\<profile> |
| gpt.properties | Defines label key values for the metadata editor's user interface and the values written to the output metadata document | \\geoportal\WEB-INF\classes\gpt\resources |
| indexables.xml* | Maps the property-meanings that should be applied to certain metadata elements to the xpath where that element can be found | \\geoportal\WEB-INF\classes\gpt\metadata\<profile> |
| property-meanings.xml | Defines property-meanings used to index metadata elements identified by the *indexables.xml file so they can be discovered through geoportal search | \\geoportal\WEB-INF\classes\gpt\metadata |
| (*) template.xml, definition.xml, and indexables.xml files will have a prefix that serves to identify them for their specific profile. For example, the prefix "dc" is seen with files of the Dublin Core profile, found in the "dc" folder within the \\geoportal\WEB-INF\classes\gpt\metadata directory, such as dc-definition.xml, dc-template.xml, and dc-indexables.xml. | ||
Note: You will notice that there are definition.xml file references in the schemas.xml that are not associated with a template.xml file. For example, in schemas.xml there is a reference to the opensearch-definition.xml file, from the \\gpt\metadata\other directory. If you open the opensearch-definition.xml file in a text editor, you notice that there is no reference to a template.xml file. This is the same for the georss-definition.xml file which is also in that same directory. These files are used to generate metadata when the Register a resource on the network publish method is chosen. Instead of a template.xml file, an xslt transformation is applied. In the opensearch and georss cases, the default transformation is to Dublin Core, using the file opensearch-toDC.xslt or georss-toDC.xslt transformations. A similar transformation is applied when OGC GetCapabilities documents are transformed into discoverable metadata for viewing in the geoportal web interface. The transformations for the OGC GetCapabilities documents are found in the \\gpt\metadata\ogc directory.
Using transformations, it is possible to transform resources into any XML structure, not just formal metadata such as ISO, FGDC, or Dublin Core.
The process for customizing the geoportal to support a new profile is defined in sections corresponding to the following steps.
- Develop a plan for your profile
- Copy the required files
- Update your template.xml file
- Update your definition.xml file
- Update gpt.properties
- Define how elements are indexed for search
- Update schemas.xml
- Finishing your profile
Before you create a custom profile, it is important to clearly define what will set your new profile apart from the profiles supported with the Geoportal Server by default. You will need to identify which of the default profiles most closely resembles your customization, and use that profile as a base to modify. It is critical that you document what new metadata elements will be added to the profile, what elements you are deleting from the profile, and any other changes you want to make.
After you've developed and documented a plan for the profile, you will need to identify obligation rules for the supported metadata elements. Obligation rules identify what is mandatory for the resource to be published in your geoportal. If a publisher attempts to publish metadata that does not contain information for a mandatory value, the document will fail validation and will not be published. Create a document that lists what elements will be mandatory, which will be optional, and which will be conditionally optional (optional unless the section is activated, for example, a browse graphic filename may become mandatory when the browse graphic section is enabled, but is optional if not enabled).
After you've identified what elements your profile will support and the obligation rules for these elements, it is important to identify the metadata XML's xpaths for all new elements to be added. If you are using an existing standard for reference, then consult the standard's documentation to get the standard xpaths. If you are defining your own that is not based on a standard, you will have to decide on an xpath convention that suits your needs.
After you've verified the xpaths for the metadata elements, you will need to design the metadata editor interface for your profile. At this step, decide how to group the items you want to include, what sections will appear in what order, and what dropdown boxes, checkboxes, radios, or text fields you want to use. It is important to look at the profile you identified as most like your desired profile as a base. Login to the geoportal as a publisher, and go to the metadata editor page for that profile. Note what design elements are pleasing and functional on that page, and note where the order of sections or elements will need to be updated, changed, or deleted for your profile.
Now that you have a plan for your profile, you will need to create the files to support it. Start by navigating to the \\geoportal\WEB-INF\classes\gpt\metadata\ folder and open the subfolder that contains the template.xml, definition.xml, and indexables.xml files that most closely matches what you desire for your custom profile. Copy these three files and paste them in this same directory, or create a new directory with your custom profile name. Rename the copied files with a prefix that distinguishes your profile from the others in the geoportal.
Note: If you want to enable the Geoportal XML Editor for your custom profile, here you will need to copy corresponding files from the applicable \\geoportal\WEB-INF\classes\gpt\gxe folder. After doing so, you should follow instructions at the following topics to customize the GXE editor: GXE Concepts, Integration with Geoportal Publication Workflow and Core Geoportal XML Editor Definition Structure.
Note: If you are enabling the GXE Editor, then you do not need to define a template.xml file, and you can skip to the next step.
The template.xml file is a skeleton metadata document that gets populated with the information the publisher enters into the online form. Your template.xml file will look like an output metadata XML document, except that its tags are not populated. In general, most of the elements in your template.xml file will be empty, except in the case where namespace validation rules require text values to be present. An example of a snippet from a template.xml file where the element must be populated is shown for the CI_RoleCode codeList element below.
<role>
<CI_RoleCode
codeList="http://www.isotc211.org/2005/resources/Codelist/gmxCodelists.xml#CI_RoleCode"
codeListValue="custodian"/>
</role>You will need to open your template.xml file for your profile in a text or XML editor, and update it to include XML tags at the correct xpath locations for the new elements that you planned to add. You will also need to delete the elements that you do not want to support from the template.xml file. Make sure that the content within the metadata elements is left empty, except in cases where the namespace requires a placeholder element to be present.
The definition.xml file is used to map important information concerning how metadata is identified, validated, generated, and displayed in the Geoportal. In older versions of the geoportal, the definition.xml file defined how the metadata creation form for a custom profile appeared, the validation rules for metadata that conformed to that profile, how the Details page for published metadata was rendered, and mapped the information input by the publisher in the metadata creation form to the template.xml file to create an output metadata document. The definition file can still do these functions, but can also be used to point to other files for these. The definition file can point to the GXE Editor files to define the metadata creation form, an xsd or Schematron to define the validation rules, and an xslt to define how the Details page is rendered.
To update the definition.xml file, open your definition.xml file in a text or XML editor. Also open the sample-schema.xml file from the \\geoportal\WEB-INF\classes\gpt\metadata folder. Study the sample-schema.xml file carefully, as it outlines what attributes should be assigned to the parameters in your definition.xml file. Now, update your definition.xml file by removing the parameters that map to the elements you removed from your template.xml file, and adding parameters that correspond to the elements you added to your template.xml file. Notice that there are sections defined in the definition.xml file. Rearrange the sections to correspond to the plan you made earlier for your metadata editor interface. Other parts of the definition.xml file that will need to be adjusted are discussed below.
Reference the Obligation rules that you wrote out earlier, which defined which elements should be mandatory and which ones optional or conditional optional. Set the parameters' obligation rules using the <validation required=""></validation> attribute for each parameter.
At the top of the definition.xml file, you will see a <schema></schema> tag. Within that tag, there is a templateFile attribute. Update this attribute to reference the name and filepath for the template.xml file for your profile.
Near the top of the definition.xml file is another important tag, called <interrogation></interrogation>. The information in this tag is used to identify if a metadata document conforms to this profile. It is very important that the count attribute in this tag can uniquely identify records that conform to your profile. It would be unwise to define an interrogation that counts the presence of common metadata elements such as a title or an abstract, as many metadata profiles use the same xpaths for these metadata elements. The best interrogations include an xpath that is mandatory according to your profile's obligation rules, but not present in other metadata profiles. For example, the ISO standard for services - ISO 19119 - uses the following as its interrogation, as other profiles will likely not have srv:SV_ServiceIdentification metadata elements:
<interrogation count="count(/gmd:MD_Metadata/gmd:identificationInfo/srv:SV_ServiceIdentification)"/>Carefully craft an interrogation that counts the presence of a mandatory element unique to your profile. This allows the geoportal to correctly identify metadata records published that conform to your profile.
You may want to provide descriptions for the input fields that appear on the metadata editor interface for your profile. These descriptions - hints - help users know what information is expected at that field in the form. They are defined in the hintMode attribute in the <input></input> tag within the <parameter></parameter>. Hint text is referenced by a bean in the gpt.properties file, and in a hintResourceKey attribute for the parameter's input. There are three different ways to define hints, each described below. Note: In these examples, the input type is text, but hints can be provided for any type of input.
- inline: displays the hint as text to the right of the input field. Example: <input type="text" hintResourceKey="catalog.general.sample.hint1" hintMode="inline"></input>
- tip: displays the hint as text that appears when the user hovers the mouse over the input field. Example: <input type="text" hintResourceKey="catalog.general.sample.hint2" hintMode="tip"></input>
- toggle: displays an icon (called "hint.gif" in the \\geoportal\catalog\images directory) to the right of the input field. When the icon is clicked, the hint text appears. Clicking the icon a second time hides the hint text. Example: <input type="text" hintResourceKey="catalog.general.sample.hint3" hintMode="toggle"></input>
The definition.xml file uses key values from the gpt.properties file to reference labels that appear on the metadata editor interface and Details page. Storing values in gpt.properties keeps track of the labels and facilitates translating the geoportal into other languages. Also, gpt.properties allows users to handle all user interface text changes in one file change, instead of searching through all the geoportal web application files to find where a certain string should be updated.
Open the gpt.properties file from the \\geoportal\WEB-INF\classes\gpt\resources directory. The structure of the file follows a bean-value syntax, described in Look and Feel of the User-Interface. You will need to add the new labels you identified while updating the definition.xml file for reference in gpt.properties. There are no requirements for naming conventions for the keys and values in gpt.properties, except that each key must be unique and begin with the word catalog. Note: begining your bean name with the word catalog is critical; if you do not, the associated string text will not appear in the geoportal user interface. It is recommended to reuse existing keys if possible.
When a user defines search criteria in the geoportal search page, the geoportal uses the lucene index to match the search criteria to metadata documents that meet that criteria. The index is defined by telling the geoportal in which metadata elements to look for certain information. For your profile, you will want certain metadata elements indexed for search. The indexables.xml file is used with the property meanings file to create the mapping between the metadata elements in your definition.xml file and the way they should be indexed. The indexables.xml file is called when a metadata document has been approved for search by a geoportal administrator user. You may need to update the indexables.xml file for your profile to index new elements that you have added. Please refer to Details of Lucene Indexing in the Geoportal for information on how the geoportal indexes terms and how to customize the meaning attributes.
When the Use dedicated editor to create metadata manually radio button is selected from Add page, the Create Metadata page loads, listing the available metadata profiles from which a publisher user can choose. This listing comes from the schemas.xml file. The geoportal also uses the schemas.xml file to identify to what profile an uploaded metadata record conforms. The geoportal interrogates the uploaded record according to the interrogation rules for each profile listed in the schemas.xml file, in the order they are listed. When the interrogation rules match the uploaded document, the geoportal stops interrogating and validates that record based on the validation rules set in that profile's definition.xml file. Thus, you see that the order of the profiles listed in schemas.xml is very important. If you have a more general interrogation rule defined in one of the metadata profiles, you will want to list that profile after you list a more specifically defined profile. For example, the interrogation rule for an ISO 19115 profile by default is <interrogation count="count(/gmd:MD_Metadata/gmd:identificationInfo/gmd:MD_DataIdentification)"></interrogation>. Any uploaded metadata document that has metadata at the MD_DataIdentification element will be classified as ISO 19115. INSPIRE metadata documents contain this element, and so do North American Profile documents. Therefore the ISO 19115 profile should be listed after INSPIRE and North American Profile in the schemas.xml file, so INSPIRE or North American Profile metadata documents can be identified by the unique INSPIRE or North American Profile interrogation rules before being interrogated as a more general ISO 19115 document.
You will need to update the schemas.xml file to support your new profile. Delete or comment-out from schemas.xml any profiles that you do not want to support, knowing that metadata documents that conform to those profiles will fail publishing when uploaded to your geoportal. Now, add a line to the schemas.xml file that directs to your profile's definition.xml file. Consider where you add the line for your supported profile in relation to the interrogation rules of the other profiles supported in your geoportal.
Note: You will notice that there are definition file references in schemas.xml that are not associated with a template file. For example, in schemas.xml there is a reference to the opensearch-definition.xml file, in the \\gpt\metadata\other directory. If you open the opensearch-definition.xml file in a text editor, you notice that there is no reference to a template file. This is the same for the georss-definition.xml file which is also in that same directory. These files are used to generate metadata when the "Register a network resource" publish method is chosen. Instead of a template.xml file, an xslt transformation is applied. In these cases, the default transformation is to Dublin Core, using the file opensearch-toDC.xslt or georss-toDC.xslt. A similar tranformation is applied when OGC GetCapabilities documents are transformed into discoverable metadata for viewing in the geoportal web interface. The transformations for the OGC GetCapabilities documents are found in the \\gpt\metadata\ogc directory.
Using transformations, is possible to transform resources into any XML structure, not just formal metadata such as ISO, FGDC, or Dublin Core.
When you have updated the template.xml, definition.xml, gpt.properties, indexables.xml, schemas.xml, and (optionally) the GXE files, make sure to save them all. Then restart your geoportal web application and launch a new instance of your geoportal. You will likely need to do some testing to refine the adjustments you've made. Once you've refined and tested, your custom standard should now be available for publishers to create metadata that conforms to your organization's specifications.