Server Configuration Options

This section includes information on the Disclosure Management server configuration options:

Registering XBRL Taxonomies

XBRL Taxonomies must be registered in the Disclosure Management Web application server. Once registered, the taxonomy can be accessed in the Disclosure Management Mapping Tool for mapping and generating XBRL instance documents. Registered taxonomies must be valid according to the XBRL specifications and include or correctly reference any taxonomy dependencies. The taxonomies that are registered are available to all Disclosure Management users in the client components. After Disclosure Management is installed, administrators must download the XBRL taxonomies manually and configure the mappingtool.properties file located in the DISCMAN_INSTANCE/config folder.

Note:

The Disclosure Management Mapping Tool page provides a Taxonomy Manager button where you can manage your taxonomy versions See Taxonomy Manager. You can also use the alternative method described in the following procedures.

Note:

The administrator is responsible for installing and registering the taxonomies that the Disclosure Management Mapping Tool uses.

Downloading the Taxonomies

Official XBRL taxonomies are usually downloaded from official taxonomy sites, such as: https://www.xbrl.org/

Required taxonomies are generally available from your regulator. Always refer to the regulator mandates and websites for instructions on which taxonomies to download.

Extracting the Taxonomies

Taxonomies must be stored and registered at the computer hosting the web application. Typically, taxonomies are downloaded in a compressed file format. When extracting a taxonomy, maintain the folder structure of the taxonomy files.

  To extract a taxonomy:

  1. If the taxonomy does not already exist in the Disclosure Management folder, locate the DISCMAN_INSTANCE/XbrlFiles folder.

  2. Uncompress the taxonomy files to the: DISCMAN_INSTANCE/XbrlFiles folder.

    Ensure that the folder structure is maintained.

  3. Ensure that the Disclosure Management Web application has read access to the XbrlFiles folder and its files.

Extending Taxonomies

To extend a taxonomy, create or edit the taxonomy in the Disclosure Management XBRL Taxonomy Designer, which is a standalone client application. Disclosure Management XBRL Taxonomy Designer is a full-featured taxonomy and instance creator. Disclosure Management XBRL Taxonomy Designer includes: creating, editing, and validating the complex taxonomies, both with single and in-reference taxonomy usage patterns and validation capabilities. With Taxonomy Designer, you can:

  • Create or rename concepts to closely match the nomenclature in your financial states

  • Change the data type, balance, and period type of concepts

  • Change the relationship of concepts

  • Change the file path where taxonomies are saved

If a taxonomy is modified, then you must register it in Disclosure Management as described in the section called “Registering XBRL Taxonomies”.

Registering and Viewing the XBRL Taxonomy Structure

When the Disclosure Management Web application is installed, a properties file named “mappingtool.properties is placed in the DISCMAN_INSTANCE/config folder. The DISCMAN_INSTANCE pertains to the computer where the Disclosure Management Web application is installed.

After the taxonomies files are unzipped on the Disclosure Management server in the XbrlFile folder, they are registered and recognized by Disclosure Management and listed in the Disclosure Management Mapping Tool. (There is no DISCMAN_INSTANCE folder in a client, for example.)

Note:

You can view and edit the mappingtool.properties file using any text editor.

Note:

Non-ASCII characters are not supported by mappingtool.properties. To use non-ASCII characters, use a unicode format (for example, \u00D2).

The mappingtool.properties file contains the following properties:

  • taxonomy_#.prefix

  • taxonomy_#.entryPoint_#

  • taxonomy_#.label_#

  • taxonomy_#.extLinkLabel_#

  • taxonomy_#.created_#

  • taxonomy_#.lastModified_#

  • taxonomy_#.package_#

  • taxonomy_#.schemaRef_#

Note:

# represents a placeholder for a numeric value. The above properties are case-sensitive.

Taxonomy Properties Example

This example shows how a mappingtool.properties file might be specified. Four taxonomies are registered:

  • US GAAP 2014

  • US GAAP 2013

  • Oracle Extension (that is, a custom taxonomy) to the US GAAP 2013 taxonomy)

  • IFRS 2014

The US GAAP 2014 taxonomy defines five entry points, but based on the schema below, the Disclosure Management Mapping Tool shows only two (“Banking and Saving” and “Commercial and Industrial”. The US GAAP 2013 taxonomy shows three entry points (“Banking and Saving”, “Commercial and Industrial”, and “Real Estate”:

taxonomy_1.prefix=us-gaap-2014
taxonomy_1.entryPoint_1=XBRLUSGAAP/ us-gaap-2014-01-31/entire/us-gaap-entryPoint-std-2014-01-31.xsd
taxonomy_1.label_1=US GAAP 2014


taxonomy_2.prefix=us-gaap-2013
taxonomy_2.entryPoint_1=XBRLUSGAAP/ us-gaap-2013-01-31/entire/ us-gaap-entryPoint-std-2013-01-31.xsd
taxonomy_2.label_1=US GAAP 2013


taxonomy_3.prefix=orcl-20140531
taxonomy_3.entryPoint_1=oracle-20140531/orcl-201405431.xsd
taxonomy_3.label_1=Oracle Q4 2014


taxonomy_4.prefix=orcl-20140831
taxonomy_4.entryPoint_1= oracle-20140831/orcl-20140831.xsd
taxonomy_4.label_1=Oracle Q1 2015

Viewing the mappingtool.properties file

Image shows mappingtool.properties file

The mappingtool.properties file includes these properties:

prefix

The prefix or “short name” is used in the Disclosure Management Mapping Tool user interface and instance documents. The prefix value must have these characteristics:

  • Has a unique value—two or more taxonomies should not use the same prefix

  • Starts with a letter or underscore character

  • Contains no spaces

  • Is short because it is used repeatedly within instance documents

entryPoint_#

The taxonomy entry point is the path to a taxonomy's .xsd file, relative to the DISCMAN_INSTANCE/XbrlFiles folder.

Taxonomies can have multiple entry points. Administrators control which entry points are registered and shown by the Disclosure Management Mapping Tool. For example, the US GAAP taxonomy has five entry points, but an administrator can choose to register only three. The website from which the taxonomy is downregistered usually contains details about its entry points.

The path to the xsd file should use the “/” character as a path separator. Alternately a double “\\” can be used, but not a single “\”, for example:

Table 1. entryPoint_#

EntryResult
us-gaap/ci/us-gaap-ci-all.xsdValid
us-gaap\\ci\\us-gaap-ci-all.xsd Valid
us-gaap\ci\us-gaap-ci-all.xsd Invalid

label_#

label_# is the user-readable label associated with the entry point.

The label is shown in the Disclosure Management Mapping Tool user interface.

Each entry point value should have a corresponding label entry.

extLinkLabel_# (Optional)

Administrators can indicate the extended link label value to be shown for extended links in the taxonomy. Two values are available: “title” or “definition”. The extended link value is defined in the extLinkLabel_1=[definition][title] property of mappingtool.properties. When one value is not available, the other is used. For example, when the value is set to “definition” and the taxonomy has only title labels, titles are used. If the property is not provided, the default value is “title”.

schemaRef_# (Optional)

The schema name (schemaRef property) in the instance document is determined by the schemaRef_# value specified in mappingtool.properties. Because this information is not supplied by the taxonomy itself, the administrator must provide the schemaRef property. The pattern for this property is: schemaRef_#=[SomeTaxonomyURI]

Note the following when specifying the schemaRef property:

  • The schemaRef property is usually a Uniform Resource Identifiers (URI) to the entry point of the taxonomy referenced by an instance document. The SEC requires that the schemaRef property point only to the taxonomy file name (see orcl-20100831.xsd.) However, the UK--IFRS requires that a full URI, (for example, http://www.xbrl.org/uk/ifrs/core/2009-09-01/uk-ifrs-full-2009-09-01.xsd") be used.

  • If it is not provided, the schema value from the corresponding entryPoint_#" property is used.

Disclosure Management supports multiple schema reference (SchemaRef) declarations in an instance document. For example, the following schema reference declarations can be specified in the mappingtool.properties file using the schemaRef_# parameter and spaces as separators: Note that the three schemaRef_# values are separated by spaces.

taxonomy_1.schemaRef_1=http://www.svs.cl/cl/fr/ci/2011-04-26/cl-ci_shell_2011-04-26.xsd http://www.svs.cl/cl/fr/ci/2011-04-26/cl-ci_ias-1_2010-04-30/cl-ci_ias-1_2010-04-30_role-210000.xsd http://www.svs.cl/cl/fr/ci/2011-04-26/cl-ci_ias-1_2010-04-30/cl-ci_ias-1_2010-04-30_role-110000.xsd

package_# (Optional)

Thepackage_# property determines whether the taxonomy files are included when users selects the “Generate XBRL” option from Microsoft Excel or Word. When this property is enabled, Disclosure Management produces the XBRL instance document on the Disclosure Management server and includes the additional documents within the compressed file (with a dmr extension). The dmr file is then serialized to the client machine and saved to the file system (as indicated by the user). When the package property is “false,”Disclosure Management does not include the dependent taxonomy files within the dmr file. Disclosure Management includes only the XBRL instance document and a few other proprietary files.

The package_# property accepts a Boolean flag value:

  • A “true” Boolean value indicates that the taxonomy files is packaged.

  • A “false” Boolean value indicates that the taxonomy file is not packaged.

if it is not provided, “true” is the default.

formatted (Optional)

The formatted property is used to automatically apply a Rich Text Format to specified data types.

Each data type must be space-separated and represented the following way: xsd_target_namespace#dataType. The pattern for the properties is: taxonomy_#.formatted=[Space separated data types]

For example, to indicate that concepts which are of the textBlockItemType data type, always use Rich Text Formatting for "taxonomy_1", add the following entry: taxonomy_1.formatted=http://xbrl.us/us-types/2009-01-31#textBlockItemType

If it is not provided, plain text formatting is always used.

unformatted (Optional)

The unformatted property is useful to automatically apply plain text format to specified data types.

Each data type must be space separated, and represented in the following way: "xsd_target_namespace#dataType". The pattern for the properties is: taxonomy_#.formatted=[Space separated data types]

For example, to indicate that concepts which are of the textBlockItemType data type always use plain text formatting for "taxonomy_1", add the following entry: taxonomy_1.unformatted=http://xbrl.us/us-types/2009-01-31#textBlockItemType

If it is not provided, plain text formatting is used.

overridable/unoverridable

You can enable or disable override functionality for a particular concept type in the mappingtool.properties file. The “overridable” and “unoverridable” properties govern whether it is possible to override all facts based on concepts of a specified type and its derived types on the Review tab.

Each item of the list in the mappingtool.properties file must be in the form of: target-name-space#dataTypeName

You need not enumerate all data types for which the override setting is enabled. Because data types are usually organized hierarchically, specify the override setting for the common parent type. For example, you could enable the override setting for the decimalItemType and its children by entering: taxonomy_1.overridable_1=http://www.xbrl.org/2003/instance#decimalItemType.

In this case, all facts based on concepts of all types inherited from decimalItemType (for example numeric, monetary, or volumeItemType) are overridable.

You can also set global override settings in addition to taxonomy specific settings, for example: global.overridable=http://www.xbrl.org/2003/instance#decimalItemType http://www.xbrl.org/2003/instance#booleanItemType http://www.xbrl.org/2003/instance#dateItemType

The unoverridable setting enables you to disable the ability to override types in the hierarchy. For example, to disable the ability to override formatted items in the US GAAP extension, you would specify: taxonomy_1.unoverridable_1= http://xbrl.us/us-types/2009-01-31#textBlockItemType.

addlinkbases

Use the addlinkbases property to add documentation for concepts in extension taxonomies. The documentation refers to the actual meaning of the concept being created. The addlinkbases property is set by specifying a space-delimited list of one or more linkbases, which you attach to a registered taxonomy. While the linkbases listed do not have to be for documentation only, it is the only resource supported at this time.

The image shows the addlinkbases property.

The most common documentation that SEC filers might attach to their extension taxonomies:

The linkbases in this are not exclusive. Several additional documentation linkbases are available for the US GAAP taxonomy. The addlinkbases property is case-sensitive (the file name should only be in lowercase characters). Additionally, the Disclosure Management service is normally restarted when the mappingtool.properties file is modified.

In the following example, the taxonomy "orcl-20101130" is a 2009 US GAAP extension taxonomy. Two documentation linkbases are attached, including one for the US GAAP concepts and one for the DEI (Document & Entity Information) concepts. Adding the two linkbases, shows the documentation (where available) when a US GAAP or a DEI concept is selected in the mapping tool. Note that the two linkbases are space separated:

taxonomy_1.prefix=Oracle

taxonomy_1.addlinkbases=http://taxonomies.xbrl.us/us-gaap/2009/elts/us-gaap-doc-2009-01-31.xml

http://taxonomies.xbrl.us/us-gaap/2009/non-gaap/dei-doc-2009-01-31.xml

taxonomy_1.label_1=Oracle 10-Q 20101130

taxonomy_1.entryPoint_1=orcl-20101130/abc-20101130.xsd

Configuring the Unit Type List

The units or currency list that is displayed when creating a unit in the Disclosure Management Mapping Tool is derived and configured in the mappingtool.properties file. Units types are available in the Measure field. The Unit type code corresponds to the ISO (International Organization for Standardization) 4217 standard. In the mappingtool.properties file, the current unit values:

  • unit_type1=shares

  • unit_type2=pure

  • unit_type3=iso4217:AED

  • unit_type4=iso4217:AUD

  • unit_type5=iso4217:CAD

  • unit_type6=iso4217:CAF

  • unit_type7=iso4217:SGD

  • unit_type8=iso4217:USD

  • unit_type9=iso4217:DEM

  • unit_type11=iso4217:NZD

  • unit_type12=iso4217:PLN

  • unit_type13=iso4217:EUR

When you create a unit type, the default unit type code is: unit_type8=iso4217:USD.

  To add or change a unit type:

  1. Navigate to mappingtool.properties file in the DISCMAN_INSTANCE/config folder.

  2. Using any text editor, open the mappingtool.properties file.

    Image shows mappingtool.properties file
  3. Scroll down to #the unit type sections.

  4. Add the new unit using the format: unit_type[number]=iso4217:[currency code].

    The currency code consists of the two-character country code and a character that represents the currency unit.

  5. Save the mappingtool.properties file.

    Unit types are validated in Review mode.

Updates to the XBRL Taxonomy

When the administrator shuts down and restarts services for Disclosure Management, the web application examines the mappingtool.properties file and detects the following changes:

  • A new taxonomy was added (that is, registered).

  • The taxonomy label or prefix is modified.

  • The content of an existing taxonomy is modified.

  • A previously registered taxonomy is removed.

Viewing Taxonomy Structure

You can view the structure of registered taxonomies in the Disclosure Management Mapping Tool in the Select Taxonomy pane. The taxonomies are shown in alphabetical order (case sensitive) in the Select Taxonomy pane.

Taxonomy Caching

Disclosure Management provides a taxonomy caching system that manages the lifecycle of a taxonomy that is registered into memory. The taxonomy caching system can be tuned using various properties.

Overview

The Disclosure Management Web application manages the loading and unloading of the XBRL taxonomies that are registered in the Disclosure Management system. Because XBRL taxonomies can be large, they tend to take up a lot of memory resources available to the Java process. Additionally, every time a taxonomy is loaded (into memory), performance is affected. Disclosure Management has a taxonomy caching system that keeps loaded taxonomies in memory so subsequent requests for taxonomy resources can be derived from the cache rather than reloading the taxonomy; the taxonomy system works as follows:

  • At startup, the taxonomy broker reads the list of registered taxonomies from the mappingtool.properties file.

  • A taxonomy cache object is created for each registered taxonomy. This does not mean that the taxonomy is loaded at this time - taxonomy loading is done on demand.

  • When a user requests a particular taxonomy, the taxonomy broker checks the corresponding taxonomy cache object:

    • If the taxonomy is already loaded, the request is fulfilled by providing the cached taxonomy.

    • If the taxonomy is not already loaded, the taxonomy is loaded into memory. (Note that this requires the additional overhead of loading the taxonomy before the user request is fulfilled.)

  • After the user request is fulfilled, the loaded taxonomy remains in memory. Any subsequent requests on the loaded taxonomy are fulfilled from the cache.

  • When a request is made on a cache taxonomy, a timestamp is registered in order to determine the “last accessed time” of the taxonomy.

  • The time stamp of the taxonomy subsequently helps to determine when it is safe to unload the taxonomy.

  • When certain criteria is met, a taxonomy is unloaded from memory. This action releases the associated resources from the web application.

The criteria used to determine if a given taxonomy should be unloaded:

  1. Available Memory—When the memory available to the Java Virtual Machine (JVM) reaches a certain threshold, the least used taxonomies are unloaded until a certain amount of memory is recovered.

  2. Unused Taxonomy—When a certain time has elapsed since a loaded taxonomy was last used or accessed, the taxonomy is unloaded.

  3. Maximum Taxonomies Loaded—When the number of taxonomies that have been loaded meets or exceeds a specified threshold, the least used taxonomies are unloaded automatically.

Taxonomy Cache Polling Feature

After a taxonomy is loaded into memory, a polling feature is provided to determine when a taxonomy can be unloaded. The polling system works in this way:

  • Every time a request is made on a taxonomy cache object, a time stamp is registered to determine the “last accessed time” of the taxonomy.

  • The time stamp subsequently helps to determine when a taxonomy cache object is a candidate for unloading; that is, Disclosure Management applies the “least recently used” or the LRU cache algorithm.

  • Disclosure Management spins two threads that are responsible for polling the taxonomy cache objects which have loaded taxonomies (in memory).

  • The first thread automatically runs every 60 seconds. It tests the amount of free memory that is available to the JVM (using the Runtime.freeMemory() Java API). If the amount of free memory is less than 1 MB, Disclosure Management automatically unloads the least recently used taxonomy cache objects until Disclosure Management has freed more than 1 MB of memory.

  • The second thread runs at a user-defined interval (using the taxonomy_cache_poll property). When this thread is enabled, the thread polls the taxonomy cache objects (with loaded taxonomies) and performs three tests to determine whether a taxonomy should be unloaded:

  • Available Memory—When the memory available to the JVM reaches a certain threshold, the least recently used taxonomies are unloaded until a certain amount of memory is recovered. This is the same test as the one performed by the first thread as discussed above. This test is covered in detail in the section called “JVM Memory Threshold ”.

  • Unused Taxonomy—When a certain time period has elapsed since a loaded taxonomy was last used or accessed, the taxonomy is unloaded.

  • Maximum Taxonomies Loaded—When the number of taxonomies loaded meets or exceeds a user–specified threshold, the least used taxonomies are unloaded automatically. See the section called “Maximum Taxonomies Loaded Threshold ”.

Cache Poll Interval

The cache poll interval property indicates the frequency or interval in which the system inspects the cached taxonomies to determines whether a taxonomy is unloaded. In the file, this property is named: taxonomy_cache_poll.

Settings for this property include:

  • Value—The value for this property is specified as an integer representing minutes.

  • Default—The default value is 5 minutes. For example, setting the property to 'taxonomy_cache_poll=5 means that all taxonomies loaded in memory are polled every 5 minutes. The thread runs every 5 minutes, after which the threshold tests (described below) are performed. If the interval is longer than the Maximum value (10 hours), Disclosure Management starts the thread every 10 hours instead of what is specified by this property.

  • Maximum: The system maximum value is 10 hours.

  • Disable—Setting the value to zero disables the polling feature. Oracle does not recommend that this feature be disabled. Other caching properties depend on the polling feature to be enabled. If this property is disabled, the only way a taxonomy is unloaded is when the JVM Memory Threshold is exceeded—or if the Disclosure Management web application is shut down or restarted.

JVM Memory Threshold

The JVM (Java Virtual Machine) memory threshold is not user configurable. When either the cache poll routines run, the first test checks how much free memory that is available of the JVM of theDisclosure Management web application. If the free memory is less than 1 MB, the least used taxonomies are automatically unloaded until the amount of available memory exceeds the threshold (1 MB). The least recently used taxonomies are determined by examining the time stamp of when a taxonomy was last used or accessed. The more time that has elapsed since a taxonomy was last used, the greater the chance that it is unloaded. The most recently used taxonomies have the best chance to remain in memory.

Least Recently Used Taxonomy Threshold

The least recently used taxonomy threshold property indicates the maximum time that can elapse since a taxonomy was last accessed before it is unloaded. In the properties file, this property is named taxonomy_cache_threshold.

Settings for this property include:

  • Value—In minutes.

  • Default—The default value is 30 minutes. For example, setting the value to 30 means that a loaded taxonomy remains in the cache (memory) for up to 30 minutes of inactivity before it is unloaded. When a new user request, which accesses a taxonomy occurs, its time stamp is reset. In this example, 30 minutes of no user requests must occur before the taxonomy is unloaded.

  • Disable—Setting the value to zero disables this feature.

Maximum Taxonomies Loaded Threshold

The maximum taxonomies loaded threshold property indicates the maximum number of taxonomies that can be loaded in the cache (memory) before the least recently used taxonomies are unloaded. In the properties file, this property is named: max_taxonomy_cached.

Settings for this property:

  • Value—Specified as a positive integer.

  • Default—The default value is 10 taxonomies. For example, setting the value to 10 means that the number of loaded taxonomies that can remain in the cache (memory) cannot exceed 10. If 10 taxonomies are currently loaded in the cache, and a request is made to load an 11th taxonomy, the least used taxonomy is unloaded.

  • Disable—Setting the value to zero disables this feature.

The “least recently used taxonomy” is determined by examining the time stamp of when a taxonomy was last used or accessed. The more time that has elapsed since a taxonomy was last used, the greater the chance that it is unloaded. The most recently used taxonomies have the best chance to remain in memory.

UBmatrix XBRL Processing Engine Settings

Disclosure Management uses the UBmatrix XBRL Processing Engine© (XPE) as the back-end engine for the majority of the XBRL processing. XPE provides a rich set of APIs that enable Disclosure Management to process and create XBRL documents. Disclosure Management uses XPE within the web application. The following section describes the settings exposed by XPE for performance and caching of XBRL documents.

The majority of the performance and caching settings for XPE can be found at: http://docs.ubmatrix.com/webhelp/XPE/3_5/.

Note that the this site should be viewed with Microsoft Internet Explorer. There are some known issues when viewing the documentation with Mozilla Firefox.

While the XPE online documentation provides details for XPE performance tuning, note the following settings:

XPE Taxonomy Caching Options

XPE provides three types of caching options:

The following are the usage points with Disclosure Management:

  • Preload—While preloading taxonomies might be useful for some users, the Disclosure Management caching system can better manage loading and unloading taxonomies. A preloaded taxonomy can eventually be unloaded by Disclosure Management (per the caching feature described above). The use of this feature is not recommended.

  • Web caching—Web caching is the recommended caching mechanism. See the section called “XPE Taxonomy Caching Overview ”.

  • Redirection—Disclosure Management does not encourage the user of redirection, which is unreliable and difficult to configure. UBmatrix recommends web caching instead of redirection.

XPE Taxonomy Caching Overview

This section provides a brief overview of the taxonomy caching framework. It is important to understand the process that XPE employs when attempting to load a taxonomy:

  • When initialized, XPE loads preloads into the document cache.

  • When a request is made to load a new taxonomy (which is not already in the document cache), XPE takes the following actions:

    • Checks the web cache first.

    • If the requested documents are not found in the web cache, XPE uses the following built-in resolver settings:

      • The documents are searched in the file system (that is, File Resolver).

      • The documents are searched in the web (that is, HTTP resolver).

      • The documents are searched using other resolvers (none of which applies to Disclosure Management).

  • If the documents are not found in the built-in resolver locations (that is, Preload and Redirection), then the document fails to load, and XPE generates an error.

Additional details about the XPE caching framework are available at: http://docs.ubmatrix.com/webhelp/XPE/3_5/default.htm#Caching/How_does_document_caching_work.htm.

XPE Web Caching

Web caching is the only XPE 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 XbrlFiles folder. 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.

Web Cache Folder

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.

Configuring the Web Cache

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 the xbrlData.properties file, 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. Oracle highly recommends setting this property default to True. 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 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.

Recommended Usage in Disclosure Management

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 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.

Allow Internet Access

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.

WorkOffline

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 and 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 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.

Provide Temporary Internet Access

You can enable XPE temporary Internet access to automatically download the required external XBRL files to an appropriate web cache folder.

  To enable XPE Temporary Internet Access:

  1. Give XPE Internet access as described in the section called “Allow Internet Access ”.

  2. Restart the Disclosure Management Web application if necessary.

  3. In the Disclosure Management add-in or in Oracle Hyperion Financial Reporting, load the taxonomy containing links to external XBRL resources. When the taxonomy is fully rendered, externally referenced XBRL documents are downloaded to the web cache folder.

  4. Disable Internet access for XPE by setting the workOffline property (in the xbrlData.properties) to true.

  5. Restart the Disclosure Management Web application.

    Note:

    The steps may be required when a new taxonomy is registered in the Disclosure Management system.

Copy Folder Structure

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 3 describes the workOffline property:

Table 3. workOffline property

PropertyDescription
TrueXPE 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.
FalseXPE 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 (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.

Using Registered Taxonomies in the Web Cache

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 the section called “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 and 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.

iXBRL Instance Generation for Importing Large Number of Mappings

If performance issues occur when generating an iXBRL instance document or importing a large number of mappings, increase the timeout period between the Oracle HTTP Server (OHS) and Oracle WebLogic app server (WL).

  To increase the timeout period for iXBRL instance documents:

  1. With any text editor, open the EPM_INSTANCE\httpConfig\ohs\config\OHS\ohs_component\mod_wl_ohs.conf file.

  2. Set the WLIOTimeoutSecs parameter to a relatively large number of seconds for the /discmanwebservices context.

    For example, you could change WLIOTimeoutSecs; to 60000 (seconds) as shown below:

    /discmanwebservices context

    <LocationMatch ^/discmanwebservices/>

    SetHandler weblogic-handler

    WeblogicCluster

    epbyminw0076.epminsk.hyperion.com:8600,epbyminw0076.epminsk.hyperion.com:8601

    DynamicServerList OFF

    WLIOTimeoutSecs 60000

    </LocationMatch>>