Web caching is the only XPE's taxonomy caching mechanisms recommended for use with Disclosure Management.
Under the Disclosure Management system, XPE typically loads a registered taxonomy from the file system. Disclosure Management registered taxonomies are installed by the Administrator under the XbrlFilesfolder. Most taxonomies are self-contained when downloaded from an official taxonomy repository (such as xbrl.org.) Some have external references to other taxonomies or XBRL documents. When this condition exists, XPE must resolve the external references to obtain the external documents. The first place XPE searches for these external documents is within its local “Web cache”. If the documents are not found in the Web cache, it searches the file system and ultimately the Internet—if access is provided to XPE.
The Web cache is a folder on the machine hosting the XPE process. In the case of Disclosure Management, it is on the server hosting the Disclosure Management Web application. Particularly, the Web cache in: %DISCMAN_HOME%\resources\System\cache.
When XPE needs to fetch any XBRL resources (external documents and/or taxonomies) from the Internet, the download files are automatically stored in the Web Cache folder. In this manner, the next time these documents are required, XPE looks for them in the Web cache folder before attempting to obtain them from another location. Additional details about the XPE cache folder are available at: http://docs.ubmatrix.com/webhelp/XPE/3_5/default.htm#Caching/How_does_web_caching_work.htm.
If you need to enable XPE to fetch requested XBRL documents from the Internet, modify the xbrlData.properties file. in the following folder: %DISCMAN_HOME%\lib\xbrlData.properties.
In xbrlData.properties, the following properties control the Web cache feature:
WorkOffline—Controls whether XPE has access to the Internet. This property is set to true by default. While it is recommended that this property is set to true, some clients do not enable Internet access to processes; especially in a server environment. When this property is set to false, administrators must ensure that the Web cache folder contains all XBRL documents used by their registered taxonomies (for details see below).
Note: | If a requested document is not available to XPE and this property is set to false, loading the requesting taxonomy may fail. See: http://docs.ubmatrix.com/webhelp/XPE/3_5/default.htm#Work_Offline.htm. |
useCache—Enable or disable the use of the Web cache folder. When this property is set to “false” the Web cache folder is completely disabled. Set to “true” by default is highly recommended. See: http://docs.ubmatrix.com/webhelp/XPE/3_5/Configuration/configuring_the_web_cache.htm.
proxyHost—Specify the proxy for XPE to use if Internet access is provided to it. Setting this property is important if a proxy must be used in order for XPE to get Internet access. By default, this property does not exist. For example, on the Oracle network, the following proxy setting can be specified: proxyHost=www-proxy.us.oracle.com:80.
See: http://docs.ubmatrix.com/webhelp/XPE/3_5/default.htm#Configuration/Configuring_a_proxy_server.htm.
Note: | Changing any of these properties requires that XPE is reinitialized, which requires a restart of the Disclosure Management Web application. |
This section provides the several usage scenarios for using the XPE Web cache feature.
XPE copies the external Web resources into the Web cache folder only if the useCache property in the xbrlData.properties file (on the Disclosure Management useCache property in the xbrlData.properties (on the Disclosure Management Web server) is set to true. This setting enables XPE to copy any external taxonomy files that it retrieved from the Web into the local Web cache folder on the Disclosure Management Web server. This setting also forces XPE to look for the externally referenced taxonomy resources in the Web cache folder before attempting to fetch them from the Internet. In this case, you must have successfully rendered the taxonomy in question at least once so that any external files were copied to the Web cache folder. Subsequent requests to render the taxonomy results in XPE looking for the external resources in the Web cache folder; thus; no Internet connection should be required. Alternately, you can manually copy the externally referenced taxonomy files to the Web cache folder. However, this is tricky because the folder structure for those files must follow the resources' namespace sequence. For example, if the namespace of the external file is http://external.com/2010/04/30/ExternalTaxonomy.xsd, copy the ExternalTaxonomy.xsd under the following folder structure: Web cache folder]\http\external.com\2010\04\30 (the http folder must be included). Note that all of these scenarios assume that the useCache property (in xbrlData.properties) is set to true. Turning off the Web cache feature is not recommended.
The easiest solution is to allow XPE Internet access so externally referenced XBRL documents are automatically downloaded and available in the Web cache folder:
The workOffline property (in the xbrlData.properties file) is set to “false”.
The useCache property is set to “true”.
Ensure that proxyHost property contains a proxy server if necessary.
You can block XPE from access to the Internet, which is preferable on a secured server environment.
Set workOffline property (in the xbrlData.properties file) to true. When working offline, the administrator must ensure that all externally referenced XBRL documents within the registered taxonomies are available in the Web cache folder.
Set useCache property to true to ensure that the necessary files in the Web cache folder are used.
When using this solution, administrators can manually fill the Web cache folder using any file transfer technique preferred (for example, ftp, copy & paste). The folder structure must represent the XBRL URI of the document. Sometimes the URI is not apparent. Administrators may need to open the XBRL document in a text editor in order to determine the folder structure.
For additional details on the Web Cache folder structure, see: http://docs.ubmatrix.com/webhelp/XPE/3_5/default.htm#Caching/How_does_web_caching_work.htm.
Another solution is to enable XPE temporary access to the Internet so that the required external XBRL files are automatically downloaded to the Web cache folder (with the appropriate folder structure). To implement this solution:
Give XPE Internet access as described in Allow Internet Access .
Restart the Disclosure Management Web application if necessary.
In the Disclosure Management add-in or in Financial Reporting, load the taxonomy containing links to external XBRL resources. When the taxonomy is fully rendered, externally referenced XBRL documents be downloaded to the Web cache folder.
Disable Internet access for XPE by setting the workOffline property (in the xbrlData.properties) to true.
Restart the Disclosure Management Web application.
Note: | The steps may be required when a new taxonomy is registered in the Disclosure Management system. |
Another solution is to enable Internet access (as described previously) on a development environment. In this environment, the administrator can access and use the taxonomies that they want to cache in the Web cache folder. The XBRL files are downloaded and installed on the development environment, the administrator can copy the entire Web cache folder from the development and put it into the Web cache folder of the production server. The production server can have the workOffline property permanently turned off. Table 8 describes the workOffline property:
Table 8. workOffline property
| Property | Description |
|---|---|
| True | XPE cannot fetch from the Internet external XBRL resources referenced within taxonomies. The danger in setting this option is that XPE does not properly process the taxonomy in question if those resources are not cached in the Web cache folder. |
| False | XPE is allowed Internet access to fetch external XBRL resources referenced within taxonomies. When external XBRL resources are required, XPE first checks the Web cache folder for the resources. If they are not there, it attempts to fetch them from the Internet. This setting assumes that XPE has an Internet connection. In many environments (such as Oracle) this requires that the HTTP proxy setting must be indicated (with the proxyHost property in the xbrlData.properties). Note that this is the default setting (meaning that when you install Disclosure Management this property is set to false). However, some companies do not allow services (such as Disclosure Management) Internet access. For these clients, “copy folder structure” is a viable solution. |
You can employ the XPE Web cache feature and register the taxonomies that exist in the Web cache, which might be useful when a base taxonomy is commonly used. For example, suppose you work with taxonomy extensions that are based on the US GAAP taxonomy. While you usually work with the US GAAP taxonomy extensions, you occasionally work with the base US GAAP taxonomy.
In this scenario, having US GAAP base files in the Web cache folder makes sense. But rather than having two copies of the US GAAP taxonomy (one in the Web cache folder and the other in the XbrlFiles folder), you can keep the US GAAP taxonomy in the Web cache folder and put a reference to the entry point in mappingtool.properties (for details on registering a taxonomy, see Registering XBRL Taxonomies):
Download or copy the base taxonomy files to the Web cache folder. The folder structure must be maintained. For example, if the 2009 US GAAP taxonomy is installed in the Web cache, it might exist in the following folder: %DISCMAN_HOME%\resources\System\cache\http\taxonomies.xbrl.us\us-gaap\2009.
Modify mappingtool.properties so a relative path is used to the new entry point of the base taxonomy. For example, to register the 2009 US GAAP Commercial & Industrial taxonomy after completing the previous step, indicate the following:
taxonomy_X.label_Y=Commercial and Industrial 2009
taxonomy_X.entryPoint_Y=../resources/System/cache/http/taxonomies.xbrl.us/us-gaap/2009/ind/ci/us-gaap-ci-stm-dis-all-2009-01-31.xsd
Note: | Note the use of the relative path ('../') at the beginning of the taxonomy_X.entryPoint_Y property. |