{"id":24425,"date":"2024-02-15T14:53:34","date_gmt":"2024-02-15T22:53:34","guid":{"rendered":"https:\/\/docs.extraview.com\/v25\/book\/configure-attachments-1\/"},"modified":"2025-04-23T09:40:06","modified_gmt":"2025-04-23T16:40:06","slug":"configure-attachments-1","status":"publish","type":"page","link":"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/","title":{"rendered":"Configure Attachments"},"content":{"rendered":"\n<div class=\"textGreyBg\">Note: It is strongly recommend that you back up your database prior to performing any of the procedures described on this page.<\/div>\n\n\n\n<p>This configuration is relevant for file attachments, document field display types and image field display types. Attachment files uploaded to ExtraView are, by default, stored as binary objects in the database. The Administrator has the choice to configure the system to store some or all of the uploaded attachments on a file system accessible to the application server. ExtraView keeps track of where all attachments are located within the database. Prior to the conversion, all attachments are marked as being stored \u201cinternally\u201d \u2013 within the database. As part of this migration process, as each individual file is extracted and copied to its final location on the file system, the system marks that attachment as now being stored \u201cexternally\u201d. The migration process may be done as a background task, without impacting the availability of attachments to the end users, at any point.<\/p>\n\n\n\n<p>This means that there is no need for a significant outage period if you have tens or hundreds of thousands of attachments to move from the database to the file system. The Administrator may choose to have all files stored internally in the database, all files stored externally in the file system, or have a mixture of some file types stored within the database, and some file types stored on the file system.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">MySQL Database Attachments<\/h3>\n\n\n\n<p>MySQL has some special considerations regarding file attachments. MySQL is very inefficient in the way it stores attachments in the database, and the Java driver software that accesses these requires a huge amount of memory for large attachments. To conserve memory, ExtraView constrains the size of MySQL attachments to 16 MBytes. Therefore, if you believe that you are likely to store and retrieve attachments larger than this size with the MySQL database, you should configure the attachments to work with external storage, where only the limitations of the operating system apply.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Configuring External Storage<\/h3>\n\n\n\n<p>To configure attachment storage options, sign on to ExtraView with the Administrator role. Click the <b>Admin<\/b> button on the navigation bar, and then choose the <b>System Controls<\/b> tab, then select <b>Environment Settings<\/b>, and edit the following settings:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><b>ATTACHMENT_REPOSITORY_OPT<\/b> &#8211; This setting controls whether attachments are stored internally within the database, externally on the file system, or in some combination of the two methods. If the value of this setting is INTERNAL (the default value), then all attachments are stored internally within the database. If the value is set to EXTERNAL, then all the attachments are stored on the external file system.<br><p>Alternatively, you may provide a comma separated list of file extensions and then all files with these extensions will be stored in the database while all others will be stored externally in the file repository. For example, if you set the value of this setting to &#8220;txt,doc,htm&#8221; then files of these types will be stored internally. This strategy leaves files of these types stored internally in the database and they remain searchable by keywords, while image and video files are stored externally. Regardless of the setting, ExtraView will continue to store dynamically generated thumbnail-sized image files in the database as these are relatively small files and must, for performance reasons, be more readily available.<\/p><br><p>There is a third value for the setting. If the value is CUSTOM, then user custom code will handle the storage of file attachments.<\/p><br><\/li>\n\n\n\n<li><b>ATTACHMENT_REPOSITORY_ROOT<\/b> \u2013 This setting defines the location outside the database where attachments will be stored. You must ensure that the path is valid from the application server(s) that are running ExtraView and that you have all the permissions to read and write to the storage. In a clustered or load-balanced environment, you must ensure that all instances of ExtraView can read and write to the same file system using this path.<br>&nbsp;<br><div class=\"textGreyBg\">Note: If you change this setting, new attachments will be saved to the new location, and existing attachments will still reference the old location. You will need to ensure that the previous file path is still accessible by the ExtraView instance, or these existing attachments will not be available to end users.<\/div><br><p class=\"required\">Ensure that you set up a backup method for this external storage as backing up your database will no longer backup the file attachments<\/p><br><\/li>\n\n\n\n<li><b>ATTACHMENT_REPOSITORY_DMAX<\/b> &#8211; This setting defines the maximum number of files or directories that are created under one node of the external directory structure. The default for this value is 999. It is not likely that this value needs to be altered.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Sizing the file system<\/h3>\n\n\n\n<p>We suggest that you ensure that there is adequate space for future growth when sizing the file system to be used for storing attachments externally. To do this, have your DBA connect to your ExtraView database using Query Analyzer (SQL Server) or SQL Plus (Oracle) and run the following queries:<\/p>\n\n\n\n<p><span class=\"fixedWidthFont\">&#8212; return the total size of the attachments stored in the database, in bytes.<br>select sum(file_size) from attachment;<br>&#8212; return the number of attachments in the database<br>select count(*) from attachment; <\/span><\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Attachment Migration Options<\/h3>\n\n\n\n<p>In order to allow current customers to easily migrate existing attachments to the file system location, a command line utility is provided to extract the attachment files out of the database and to save them to the file system. This step is only required if you wish to extract the existing attachments from the database and store them on a file system on your network. You must pass several parameters into the ExtraView command line utility:<\/p>\n\n\n\n<p>You can move one attachment by providing either a single attachment ID:<\/p>\n\n\n\n<p><span class=\"fixedWidthFont\">doAttachmentMigration &#8220;-id 10000&#8221;<\/span><\/p>\n\n\n\n<p>or you can move batches of attachments by providing a range of attachment IDs:<\/p>\n\n\n\n<p><span class=\"fixedWidthFont\">doAttachmentMigration &#8220;-from 10000 -to 50000&#8221;<\/span><\/p>\n\n\n\n<p>Attachment ID values can be found by having your DBA run the following SQL query against the ExtraView database:<\/p>\n\n\n\n<p><span class=\"fixedWidthFont\">select min(attachment_id), max(attachment_id) from attachment;<\/span><\/p>\n\n\n\n<p>Optional parameters can be added inside the double quotes in the command line parameters:<\/p>\n\n\n\n<p><span class=\"fixedWidthFont\">-report <em>filename<\/em><\/span>&nbsp; &#8211; Generates a specific report file (by default the report will be dumped into ExtraView log file)<\/p>\n\n\n\n<p><span class=\"fixedWidthFont\">-delete<\/span> &#8211; If specified, this deletes the attachment content blob from the database after it has been migrated successfully. We would not generally recommend this if you have a large number of attachments, as it is much more efficient to simply have your DBA truncate the table when you have completed the migration and have validated your results.<\/p>\n\n\n\n<p><span class=\"fixedWidthFont\">-testOnly<\/span> &#8211; This allows a dry run of the attachment migration without any modification to the database or the repository.<\/p>\n\n\n\n<p><span class=\"fixedWidthFont\">-noValidation<\/span> &#8211; This prevents the CRC-32 check on the stored migrated attachments, and may be somewhat faster. Use of this parameter is not recommended, because the extra time to validate the file content vis-\u00e0-vis the blob content is nominal, and the consequences of storing a blob in the file system incorrectly due to I\/O error or network error could include a loss of valuable data. If the CRC-32 validation fails, the attachment is not migrated and an error is posted to the log and\/or report file.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Running the Migration Utility<\/h3>\n\n\n\n<p>The migration command line utility is included in the ExtraView application package. It requires Java be installed on the application server where you run it. We provide shell and batch file scripts that you can use to run the utility. If you have deployed ExtraView in a WAR\/EAR file, you will need to set up an exploded directory to run this script. The scripts are located in the <span class=\"fixedWidthFont\">evj\/WEB-INF\/data<\/span> folder on your application server.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><b>Windows Tomcat<\/b> Edit the <span class=\"fixedWidthFont\">doAttachmentMigration.bat<\/span> file Locate the lines:<br><p><span class=\"fixedWidthFont\">set JAVA_HOME=%1<br>set TOMCAT_HOME=%2<br>set EV_BASE=%3<\/span><\/p><br><p>Replace <span class=\"fixedWidthFont\">%1<\/span> with your path to Java (e.g. <span class=\"fixedWidthFont\">C:\\ExtraView\\jre1.7.0_67<\/span>)<\/p><br><p>Replace <span class=\"fixedWidthFont\">%2<\/span> with your path to Tomcat (e.g. <span class=\"fixedWidthFont\">C:\\ExtraView\\Tomcat7<\/span>)<\/p><br><p>Replace <span class=\"fixedWidthFont\">%3<\/span> with your path to ExtraView (e.g. <span class=\"fixedWidthFont\">C:\\ExtraView\\Tomcat7\\webapps\\evj<\/span>)<\/p><br><p>Save and exit the edit session. Open a command window in the <span class=\"fixedWidthFont\">evjWEB-INFdata<\/span> folder and type the following command:<\/p><br><p><span class=\"fixedWidthFont\">doAttachmentMigration &#8220;parameters&#8221;<\/span><\/p><br><p>where <span class=\"fixedWidthFont\">&#8220;parameters&#8221;<\/span> is a double-quote enclosed list of parameters as per the options listed above<br>&nbsp;<\/p><br><\/li>\n\n\n\n<li><b>Linux Tomcat<\/b> Edit the <span class=\"fixedWidthFont\">doAttachmentMigration.sh<\/span> file Locate the lines:<br><p><span class=\"fixedWidthFont\">TOMCAT_HOME=\/usr\/local\/extraview\/tomcat<br>JAVA_HOME=\/usr\/local\/extraview\/java<\/span><\/p><br><p>Set <span class=\"fixedWidthFont\">TOMCAT_HOME<\/span> and <span class=\"fixedWidthFont\">JAVA_HOME<\/span> to your correct paths for your installation.<\/p><br><p>Save and exit the edit session.<\/p><br><p>At the command prompt, type the following command:<\/p><br><p><span class=\"fixedWidthFont\">sh doAttachmentMigration.sh &#8220;parameters&#8221;<\/span><\/p><br><p>where <span class=\"fixedWidthFont\">&#8220;parameters&#8221;<\/span> is a double-quote enclosed list of parameters as per the options listed above<br><\/p><\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Image Field Migration<\/h3>\n\n\n\n<p>To migrate fields with a display type of IMAGE, please see <a href=\"v25..\/administration-guide-1\/appendices-6\/document-image-field-migration-1\" data-type=\"page\" data-id=\"24221\">this<\/a> page.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Validation and Completion<\/h3>\n\n\n\n<p>While the migration utility runs, it displays information on the console. It will also write detailed log entries to a file in the <span class=\"fixedWidthFont\">evj\/WEB-INF\/log<\/span> folder (or to the file defined in the <span class=\"fixedWidthFont\">-report<\/span> parameter option). Once the process has completed, you can check the log file to determine if there were any problems. If all attachments were migrated, you can verify that the attachments are available to download and view through the ExtraView GUI. Once you are satisfied, you can have your DBA remove the binary attachments from the database.<\/p>\n\n\n\n<p>If you have selected the option to have all attachments stored in the file system, your DBA can simply run the command:<\/p>\n\n\n\n<p><span class=\"fixedWidthFont\">update attachment set thumbnail_id = null where thumbnail_id is not null;<br>truncate table attachment_content;<\/span><\/p>\n\n\n\n<div class=\"textGreyBg\">Note: this will remove all thumbnails. The thumbnail will be regenerated dynamically the next time the attachment is referenced, e.g., as part of a detailed report.<\/div>\n\n\n\n<p>If you have selected the option of having some types of file stored in the database and some files stored externally, your DBA will need to run some variant of:<\/p>\n\n\n\n<p><span class=\"fixedWidthFont\">delete from attachment_content<br>where attachment_id in<br>( select attachment_id<br>&nbsp; from attachment<br>&nbsp; where STORED_INTERNAL = \u2018N\u2019 );<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Note: It is strongly recommend that you back up your database prior to performing any of the procedures described on this page. This configuration is relevant for file attachments, document field display types and image field display types. Attachment files uploaded to ExtraView are, by default, stored as binary objects in the database. The Administrator&#8230;<\/p>\n","protected":false},"author":1,"featured_media":0,"parent":24363,"menu_order":30,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_acf_changed":false,"_lmt_disableupdate":"no","_lmt_disable":"","_kad_blocks_custom_css":"","_kad_blocks_head_custom_js":"","_kad_blocks_body_custom_js":"","_kad_blocks_footer_custom_js":"","_kad_post_transparent":"","_kad_post_title":"","_kad_post_layout":"","_kad_post_sidebar_id":"","_kad_post_content_style":"","_kad_post_vertical_padding":"","_kad_post_feature":"","_kad_post_feature_position":"","_kad_post_header":false,"_kad_post_footer":false,"footnotes":""},"class_list":["post-24425","page","type-page","status-publish","hentry"],"acf":[],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v25.1 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>Configure Attachments - Product Documentation<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Configure Attachments - Product Documentation\" \/>\n<meta property=\"og:description\" content=\"Note: It is strongly recommend that you back up your database prior to performing any of the procedures described on this page. This configuration is relevant for file attachments, document field display types and image field display types. Attachment files uploaded to ExtraView are, by default, stored as binary objects in the database. The Administrator...\" \/>\n<meta property=\"og:url\" content=\"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/\" \/>\n<meta property=\"og:site_name\" content=\"Product Documentation\" \/>\n<meta property=\"article:modified_time\" content=\"2025-04-23T16:40:06+00:00\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"8 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/\",\"url\":\"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/\",\"name\":\"Configure Attachments - Product Documentation\",\"isPartOf\":{\"@id\":\"https:\/\/docs.extraview.com\/v25\/#website\"},\"datePublished\":\"2024-02-15T22:53:34+00:00\",\"dateModified\":\"2025-04-23T16:40:06+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/docs.extraview.com\/v25\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"ExtraView 25\",\"item\":\"https:\/\/docs.extraview.com\/v25\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Installation &#038; Upgrade Guide\",\"item\":\"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/\"},{\"@type\":\"ListItem\",\"position\":4,\"name\":\"Configure Attachments\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/docs.extraview.com\/v25\/#website\",\"url\":\"https:\/\/docs.extraview.com\/v25\/\",\"name\":\"ExtraView Product Documentation\",\"description\":\"ExtraView Documentation\",\"publisher\":{\"@id\":\"https:\/\/docs.extraview.com\/v25\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/docs.extraview.com\/v25\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/docs.extraview.com\/v25\/#organization\",\"name\":\"ExtraView Corporation\",\"url\":\"https:\/\/docs.extraview.com\/v25\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/docs.extraview.com\/v25\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/docs-stg.extraview.com\/wp-content\/uploads\/2024\/03\/favicon.png\",\"contentUrl\":\"https:\/\/docs-stg.extraview.com\/wp-content\/uploads\/2024\/03\/favicon.png\",\"width\":512,\"height\":512,\"caption\":\"ExtraView Corporation\"},\"image\":{\"@id\":\"https:\/\/docs.extraview.com\/v25\/#\/schema\/logo\/image\/\"}}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Configure Attachments - Product Documentation","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/","og_locale":"en_US","og_type":"article","og_title":"Configure Attachments - Product Documentation","og_description":"Note: It is strongly recommend that you back up your database prior to performing any of the procedures described on this page. This configuration is relevant for file attachments, document field display types and image field display types. Attachment files uploaded to ExtraView are, by default, stored as binary objects in the database. The Administrator...","og_url":"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/","og_site_name":"Product Documentation","article_modified_time":"2025-04-23T16:40:06+00:00","twitter_card":"summary_large_image","twitter_misc":{"Est. reading time":"8 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/","url":"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/","name":"Configure Attachments - Product Documentation","isPartOf":{"@id":"https:\/\/docs.extraview.com\/v25\/#website"},"datePublished":"2024-02-15T22:53:34+00:00","dateModified":"2025-04-23T16:40:06+00:00","breadcrumb":{"@id":"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/configure-attachments-1\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/docs.extraview.com\/v25\/"},{"@type":"ListItem","position":2,"name":"ExtraView 25","item":"https:\/\/docs.extraview.com\/v25\/"},{"@type":"ListItem","position":3,"name":"Installation &#038; Upgrade Guide","item":"https:\/\/docs.extraview.com\/v25\/extraview-25\/installation-upgrade-guide-1\/"},{"@type":"ListItem","position":4,"name":"Configure Attachments"}]},{"@type":"WebSite","@id":"https:\/\/docs.extraview.com\/v25\/#website","url":"https:\/\/docs.extraview.com\/v25\/","name":"ExtraView Product Documentation","description":"ExtraView Documentation","publisher":{"@id":"https:\/\/docs.extraview.com\/v25\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/docs.extraview.com\/v25\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Organization","@id":"https:\/\/docs.extraview.com\/v25\/#organization","name":"ExtraView Corporation","url":"https:\/\/docs.extraview.com\/v25\/","logo":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/docs.extraview.com\/v25\/#\/schema\/logo\/image\/","url":"https:\/\/docs-stg.extraview.com\/wp-content\/uploads\/2024\/03\/favicon.png","contentUrl":"https:\/\/docs-stg.extraview.com\/wp-content\/uploads\/2024\/03\/favicon.png","width":512,"height":512,"caption":"ExtraView Corporation"},"image":{"@id":"https:\/\/docs.extraview.com\/v25\/#\/schema\/logo\/image\/"}}]}},"taxonomy_info":[],"featured_image_src_large":false,"author_info":{"display_name":"carl.koppel","author_link":"https:\/\/docs.extraview.com\/v25\/author\/carl-koppel\/"},"comment_info":0,"_links":{"self":[{"href":"https:\/\/docs.extraview.com\/v25\/wp-json\/wp\/v2\/pages\/24425","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/docs.extraview.com\/v25\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/docs.extraview.com\/v25\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/docs.extraview.com\/v25\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/docs.extraview.com\/v25\/wp-json\/wp\/v2\/comments?post=24425"}],"version-history":[{"count":4,"href":"https:\/\/docs.extraview.com\/v25\/wp-json\/wp\/v2\/pages\/24425\/revisions"}],"predecessor-version":[{"id":29747,"href":"https:\/\/docs.extraview.com\/v25\/wp-json\/wp\/v2\/pages\/24425\/revisions\/29747"}],"up":[{"embeddable":true,"href":"https:\/\/docs.extraview.com\/v25\/wp-json\/wp\/v2\/pages\/24363"}],"wp:attachment":[{"href":"https:\/\/docs.extraview.com\/v25\/wp-json\/wp\/v2\/media?parent=24425"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}