Cache Builder

The Cache Builder is a command line utility that pre-populates the Colectica Portal cache with various information. Pre-populating the cache greatly improves performance as users browse the site.

Cached Information

The following table describes the information that can be cached by CacheBuilder.

Command Location Functionality Required for functionality
elastic Elasticsearch Search Yes
breadcrumbs Disk Search breadcrumbs Yes
pdf Disk Per-item PDF downloads No
data Elasticsearch Custom data extracts Yes
learn Disk “Also Viewed” lists Yes
sitemap Disk Sitemaps Yes

If Elasticsearch is not populated, search will fall back to the basic Repository search.

If the breadcrumb is not populated, search will still work but the search results will not show breadcrumbs.

If the PDF cache is not populated, per-item PDF downloads will still work, and PDFs will be cached as they are created.

If the data cache is not populated, custom data extract functionality will not be available.

If “learn” is not run, item pages will not show the “Also Viewed” lists.

If sitemaps are not generated, the sitemap functionality will not be available.

Deploy the Cache Builder

  1. First, make sure Colectica Repository and Colectica Portal are installed.

  2. Populate Colectica Repository with metadata.

  3. Download the Cache Builder package. This will be named and should be included with your Colectica Portal delivery.

  4. Before extracting the Cache Builder package, make sure Windows does not have the file blocked. To check this:

    1. In Windows Explorer, right click the Zip file and choose Properties.
    2. Near the bottom of the Properties window, in the Security area, see if there is a checkbox labeled Unblock.
    3. If there is an Unblock checkbox, check the box and click OK.
    4. If there is no such checkbox, proceed to the next step.
  5. Extract the contents of the Cache Builder package. In this documentation, the directory to which you extract the file will be referred to as CacheBuilderDir\.

Configure the Cache Builder

  1. Navigate to CacheBuilderDir\.

  2. If there is not a file named appsettings.json, then copy the appsettings.json.dist file to appsettings.json.

  3. In the appsettings.json file, update the following settings.

    Data - DefaultConnection - ConnectionString

    The full connection string of the database to use to store authentication tables, when using Colectica Portal’s built in user management.

    Data - ColecticaRepository - ConnectionString

    The full connection string of the Colectica Repository database.

    Elasticsearch - UserAttributes

    Optional. CustomFields and UserAttributes are automatically indexed for full text search. If any fields should be stored verbatim instead of being tokenized, use this configuration field. For example:

    "Elastic": {
        "UserAttributes": [
           "title": "LifeStage",
           "analyzer": "not_analyzed"


    The ConnectionString settings should match the settings in the Colectica Portal configuration.

Run the Cache Builder

  1. Open a command shell and navigate to CacheBuilderDir\.

  2. Run the following command:

    Colectica.CacheBuilder.exe {hostname} all

    Be sure to replace {hostname} with the actual hostname used to access your site (e.g.,

    Instead of specifying all, see the table above for individual caching options.


    For tasks that store information in Elasticsearch, you may specify an index name instead of a hostname. The active elastic index can be configured in the Colectca Portal appsettings.json file. See Database, Search, and Cache Configuration.


Depending on the size of your data, the Cache Builder may take a long time to run. The advantage of taking the time to run the Cache Builder is that performance will be much faster for your web users.