Create and configure the Metadata Service for Metadata Explorer

Summary

Instructions provided describe how to set up a fully functional Metadata Explorer Web Application for the Metadata Service.

To have the Metadata Explorer Web Application working properly, the database must be properly configured, Metadata and SearchMap Services must be created, authentication must be enabled, and the Metadata Explorer Web Application must be configured.

This article covers the following steps:

• Configuring the database for the Metadata Service.
• Configuring the map configuration file (.axl) for the Metadata Service.
• Creating the Metadata and SearchMap Services.
• Deploy and Configure Metadata Explorer to use the Metadata and SearchMap Services.
• Enabling and configuring authentication so that metadata documents can be published to the Metadata Server Service.
• Publishing documents to the Metadata Service.
• Using the Metadata Explorer Web Application to view published metadata documents.

Procedure

1. Configure the database that will store the metadata documents.

   Oracle 8.x, 9.x, 10G:

   1. Create a new table space that is 550 MB in size.
   2. Create a new Oracle user. Make the table space created in step A the default table space for the new user.
   3. On the Role tab, grant connect and resource permissions to the new user.
   4. Click the Create button to create the new user.

   SQL Server 2000:

   1. Create a new database that is 600 MB in size. This can be done by running the ArcSDE post installation.
   2. Create a new user SQL Server user. Make the Default database for the user the database specified in step A. On the Database Access tab, grant the new user access to the database created in step A.
   3. Click OK to create the new user.
   4. Under Databases, right-click on the database created in step A and click the Properties button. Click on the Permissions tab and grant the following permissions to the user created in steps B and C:
      • Create Table
      • Create View
      • Create SP
      • Create Function
   5. Click OK.
2. Configure the database for full text indexing.

   Oracle 8.x, 9.x, 10G:

   The Metadata Service is reliant on Oracle Text so that ArcSDE XML columns can be used. Oracle text is typically installed by default. If Oracle text was not installed or the database was upgraded from a previous version, contact the database administrator.
   Oracle text for the Metadata Service can be configured by using one of the following methods:

   Using SQL*Plus:

   1. Log in to SQL*Plus as the ctx_sys user.
   2. Grant privileges to the user who will own the XML column by issuing the command:

      sql>grant execute on ctx_ddl to <username>;

      Note:
      <username> is the user who will own the XML column.  should be replaced with the name of the user created in Step 1.
      

   Using Oracle Enterprise Manager:

   1. Log in to Oracle Enterprise Manager as SYSDBA.
   2. Navigate to Network > Databases > <Database_name> > Security > Users.
   3. Click the user that was created in step 1.
   4. Click the Object tab. Click CTXYSYS > Packages > CTX_DDL. Under 'Available Privileges', click on 'EXECUTE' and the down arrow to grant permissions on this object.
      The table space and user that will store the metadata tables is now configured for Oracle text.

      Note:
      More information regarding the configuration of SQL Server for full text searches can be found on page 100 in the Creating Metadata Services Guide.

   SQL Server 2000:

   The Metadata Service is reliant on the SQL Server full text search engine so that ArcSDE XML columns can be used. The full text search engine is installed by default. To see if the full text search engine is installed, run the following query in SQL Server Query Analyzer:

   SELECT
   fulltextserviceproperty('IsFulltextInstalled')

   If a value of 1 is returned, the full text search engine is installed. If a value of 0 is returned, the full text search engine is not installed. Contact the database administrator if the full text search engine is not installed.
   
   To enable the database that stores the metadata documents for full text searches, perform the following steps:
   1. In SQL Server Enterprise Manager, right-click on the database that will contain the Metadata Service tables.
   2. Click New > Full-Text Catalog ...
   3. For Name, enter SDE_DEFAULT_CAT.
   4. For Location, accept the default or specify the appropriate location.
   5. Click OK.
      
      The database that will store the metadata tables is now configured for full text searches.

      Note:
      More information regarding the configuration of SQL Server for full text searches can be found on page 106 in the Creating Metadata Services Guide .

3. Configure the metadataserver.axl file.
   • To create the Metadata Service, three important ArcXML elements and their respective attributes must be populated. The SDEWORKSPACE, METADATA_CONTENT and TABLE_NAME elements must be configured properly in the metadataserver.axl file.
     
     Open the metadataserver.axl file, which is typically located in the C:\ArcIMS\axl\metadata folder.
     
     SDEWORKSPACE:
     The following parameters must be included and populated in the SDEWORKSPACE element:
     
     name: any name (string) works.
     server: name of the ArcSDE server.
     instance: port or service name on which the ArcSDE giomgr process listens.
     database: the database that contains the metadata documents if using SQL Server. Oracle does not use the concept of databases, so this attribute will be left blank by Oracle users.
     user: ArcSDE user name created by the database administrator.
     password: password for ArcSDE user created by the database administrator.
     
     SQL Server example:

     <SDEWORKSPACE name="sde_ws-0" server="payette" instance="port:5151" database="metadata" user="meta" password="kjdkjr" />

     Oracle example:

     <SDEWORKSPACE name="sde_ws-0" server="payette" instance="port:5151" database="" user="meta" password="kjdkjr" />

     Note:
     More information regarding the SDEWORKSPACE element can be found in the ArcXML Programmer's Reference Guide.

     
     METADATA_CONTENT:
     By default, the validate and index_words attributes are populated. The values for each of these attributes may need to be changed depending on the needs and workflow of the organization.
     
     validate: Set validate to 'true' or 'false'. When set to true, documents are validated before they are published to ensure they contain the five pieces of information required for Metadata Explorer and ArcCatalog. If validate is set to true, the five required pieces of information required in the metadata document are the following: Citation Title, Title, Publisher, Spatial Domain (Bounding Coordinates and G-Polygon), and Theme Keyword. If validate is set to false, documents can be published to the Metadata Service as is.
     
     index-words: To do a text search on a document, the document must be indexed. Text indexes can be updated immediately after documents are published. In general, set index_words to automatic for SQL Server and change it to manual for Oracle. With the manual setting, the database’s text indexes must be updated using the aimsmetaindx command or database tools.
     
     Oracle or SQL Server example:

     <METADATA_CONTENT validate="true" index_words="automatic" />

     Note:
     More information about the aimsmetaindx utility can be found on page 35 in the Creating Metadata Services Guide. In addition, further information regarding the METADATA_CONTENT element can be found on page 27 in the Creating Metadata Services Guide as well as in the ArcXML Programmer's Reference Guide.

     TABLE_NAME:
     The ArcXML TABLE_NAME element contains a single attribute called prefix. The prefix attribute defines the names of the tables that will be created in the database when the Metadata Service is started. The default value of imsmetadata can be used or this can be changed to suit the needs of the organization.
     
     Oracle or SQL Server example:

     <TABLE_NAME prefix="imsmetadata" />

     After populating the appropriate attributes for the SDEWORKSPACE, METADATA_CONTENT and TABLE_NAME elements, save and close the metadataserver.axl file.
4. Create the Metadata and SearchMap Services.
   
   Metadata Service:
   1. Open ArcIMS Administrator and click on the services button.
   2. Click the New Service button.
   3. For service name, enter Metadata.
   4. For .axl file, browse to and select the metadataserver.axl file, which is typically located in the C:\ArcIMS\axl\Metadata folder.
   5. For Virtual Server, select MetadataServer1.
   6. For Directory Location and HTTP Location (URL), accept the defaults or change the locations based on the needs of the organization.
   7. Click OK.
   SearchMap service:
   8. Click the New Service button.
   9. For service name, enter SearchMap.
   10. For .axl file, browse to and select the searchmap.axl file, which is typically located in the C:\ArcIMS\axl\Metadata folder.
   11. For Virtual Server, select ImageServer1.
   12. For Image Type, select the output image format that best suits the needs of the organization.
   13. For Directory Location and HTTP Location (URL), accept the defaults or change the locations based on the needs of the organization.
   14. Click OK.
5. Deploy and Configure Metadata Explorer to use the Metadata and SearchMap Services.
   • Deploy the Metadata Explorer Web Application:
     1. Deploy the Metadata Explorer Web Application on the Web server. The deployment method depends on the Web Server/Servlet Engine combination that is used. See step 4: Configure your Web Server in the ArcIMS Installation Guide for instructions regarding this.
   • Configure the Metadata Explorer aimsmeta.properties file:
     2. Open the aimsmeta.properties file in with a text editor.

        Note:
        The location of this file is different for each different servlet engine. Refer to page 87 in the Creating Metadata Services Guidefor the location of the aimsmeta.properties file.

     3. Edit the following parameters in the aimsmeta.properties file.
        
        meta_service_name: Enter the name of the Metadata Service created in step 4. Typically, <b>Metadata</b> will be the service name that is entered. The name of this service may be different based on the needs of the organization.
        
        meta_host_name: This will be the name of the machine on which the ArcIMS Application Server is running. Enter the name of the ArcIMS Application Server machine. This parameter is typically populated during the ArcIMS Post installation, so there may not be a need to edit this parameter.
        
        meta_port_number: The port number on which the ArcIMS Application Server listens for requests. Typically, the value will be 5300. Change the port number to the number on which the ArcIMS Application server listens if this has been modified.
        
        search_service_name: Enter the name of the searchmap service created in step 4. Typically, SearchMap will be the service name that is entered. The name of this service may be different based on the needs of the organization.
        
        search_host_name: This will be the name of the machine on which the ArcIMS Application Server is running. Enter the name of the ArcIMS Application Server machine. This parameter is typically populated during the ArcIMS Post installation, so there may not be a need to edit this parameter.
        
        search_port_number: The port number on which the ArcIMS Application Server listens for requests. Typically, the value will be 5300. Change the port number to the number on which the ArcIMS Application server listens if this has been modified.

        Note:
        It is possible for the Metadata and SearchMap Services to run on different machines but be used in one Metadata Explorer Web Application. Because of this, the host_name and port_number parameters must be specified for each service.

     4. Save and close the aimsmeta.properties file.
     5. Restart the servlet engine.
     6. Test the Metadata Explorer Web Application by entering the following URL:

        http://<machine_name>/metadataexplorer/

        
        When the Metadata Explorer Web Application opens, the SearchMap Service should appear in the upper left portion of the site. Click on the 'Browse' tab to ensure that the application is working properly. Metadata documents do not appear because no metadata documents have been published to the Metadata Service.
        
        If "An Error has occurred. Please try again later" message appears, check the following:
        1. Confirm the Metadata and SearchMap Services are running in Administrator.
        2. Confirm that the spelling of the SearchMap and Metadata Service names in Administrator match the SearchMap and Metadata Service name parameters in the aimsmeta.properties file. These service names are case-sensitive.
        3. Confirm that the servlet engine has been restarted.
6. Enable Authentication.
   • To publish metadata documents to the Metadata Service, a user must have the proper publishing permissions. A user must enter a user name and password to gain access to the Metadata Service. The process of verifying user names and passwords is called authentication. A user's ability to publish metadata also depends on the role granted by the site administrator. For a detailed description of metadata roles, see page 29 in the Creating Metadata Services Guide.
   • User names, passwords, and roles are stored in an access control list (.acl). The access control listed can be implemented by using a text file or with Java Database Connectivity (JDBC). For the purposes of this article, a text-based .acl file will be used.

     Note:
     Information regarding the implementation of authentication using a JDBC connection can be found in the ArcIMS Help Guide. Click Start > Programs > ArcGIS > ArcIMS > ArcIMS Help > Advanced Topics > Restricting user access to services > User authentication in the Servlet Connector > Enabling authentication with a JDBC-based ACL.

   Create the aimsacl.xml file:

   1. Create an ACL file with a text editor and name it aimsacl.xml.
   2. Define user name and password pairs that provide access to the ArcIMS services.
   3. List the services that can be accessed with the user name and specify a role.
      
      The following is a sample .acl file that demonstrates a typical metadata service configuration. The name of the metadata service is Metadata. There are two additional image services: Searchmap and Australia.

      <?xml version="1.0"?>
      <AIMSACL>
      <USER name="*" services="SearchMap,Australia" />
      <USER name="browse" password="browse" services="Metadata" roles="metadata_browser" active="1" />
      <USER name="publish" password="publish" services="Metadata" roles="metadata_publisher" active="1" />
      <USER name="author" password="author" services="Metadata" roles="metadata_service_author" active="1" />
      <USER name="admin" password="admin" services="Metadata" roles="metadata_administrator" active="1" />
      </AIMSACL>

   4. Save and close the aimsacl.xml file.
      
      Enable Authentication:
      
      Authentication is enabled by editing the Servlet Connector Properties file (Esrimap_prop). Open the Esrimap_prop file and make the following changes.

      enable=True
      authenticate=True
      authMethods=Digest
      authenticateWithSessions=True
      sessionTimeout=120
      aclFileName=<path_to_file>/aimsacl.xml
      realm=ArcIMS Network

      Warning:
      Make sure to remove the comment out (#) sign before each parameter. If the # sign is not removed, authentication will not function properly and users will not be able to publish metadata documents.

      Note:
      The location of the Esrimap_prop file differs depending on the servlet engine used.

      Below is a list of common Web server/servlet engine combinations and their servlet directory locations to find the Esrimap_prop file:
      
      ServletExec 5.0 Application Server
      <ServletExec Installation Directory>\ServletExec AS\se-<instance-name>\Servlets\
      ServletExec 4.x and 5.x ISAPI
      <ServletExec Installation Directory>\ServletExec ISAPI\Servlets
      Tomcat 4.1.xx/5.0.28
      <Tomcat installation directory>\webapps\servlet\WEB-INF\classes\
      Sun Java System (formerly Sun ONE) Application Server 7.0
      <Sun Java System 7.0 Installation Directory>\domains\domain1\server1\applications\j2eemodules\arcimsservletconnector_1\WEB-INF\classes\
      Tomcat 4.1.xx and 5.0.xx
      <Tomcat Installation Directory>\webapps\servlet\WEB-INF\classes\
      WebLogic 7.0
      <WebLogic Installation Directory>\user_projects\applications\<domain>\DefaultWebApp\WEBINF\classes
      
      JRun
      
      <JRun Installation Directory>\Oracle\iSuites\Apache\Jserv\servlets\
      
      WebSphere
      <WebSphere Installation directory>\AppServer\installedApps\<servername>\arcimsservletconnector.war.ear\arcimsservletconnector.war\WEB-INF\classes
   5. Restart the servlet engine for the changes in the aimsacl.xml and esrimap_prop files to occur. If the servlet engine is part of the Web server, start and stop the Web server.
7. Use ArcCatalog to publish metadata to the Metadata Service.
   1. Open ArcCatalog and establish a connection to the Metadata Service. Click on 'GIS Servers' and 'Add ArcIMS Server'.
   2. For 'URL of Server', specify the name of the server where the Metadata Service is running.
   3. Enter a user name and password that was specified in the aimsacl.xml file. This step is important to ensure that a user with sufficient publishing permissions is able to publish metadata documents.
   4. To test if authentication is working properly, right-click on the Metadata Service and click 'New Folder'.

      Note:
      If the creation of a new folder fails, recheck the instructions in step 6 for enabling authentication.

   5. In ArcCatalog, click the item whose metadata is to be published. To select more than one item in the Contents tab, hold down the Ctrl key while clicking the items.
      
      These datasets should already have metadata.

      Note:
      If metadata has not been created for the datasets that the user is trying to publish, see pages 48 - 53 in the Creating Metadata Services Guide for steps on preparing metadata for publishing.

   6. Click the Copy button.
   7. Click the folder in the ArcIMS Metadata Service to which the metadata is going to be published or click directly on the Metadata Service.
   8. Click the Paste button. The published documents appear in the ArcIMS metadata folder. Publishing can take a few moments.

      Note:
      If any problems are encountered, a report appears, indicating why a document could not be published. If any documents were previously published, the report also shows which documents were updated.