appsettings.json

To configure the application, you can edit the appsettings.json file.

  1. Navigate to RepositoryDir/.

  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 settings. Each of the available settings is described below.

Required Configuration Fields

These settings must be configured in order for Colectica Repository to work.

DiskCachePath

The disk location on the server where cache files can be stored.

Data:DefaultConnection:ConnectionString

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

Data:DefaultConnection:ProviderName

The name of the database provider. Either System.Data.SqlClient or Npgsql.

Data:ColecticaRepository:ConnectionString

The full connection string of the Colectica Repository database.

Data:ColecticaRepository:ProviderName

The name of the database provider. Either System.Data.SqlClient or Npgsql.

UseWindowsAuthentication

Set to true if using Windows authentication; otherwise set to false. Setting true will also disable JWT token authentication in the REST application and Windows Authentication will be enabled.

See below for sample database connection strings.

SMTP Configuration

SMTP configuration is used for sending notification emails, including password reset emails. If configuration is not provided, emails will not be sent.

Smtp:Host

The host name of the SMTP server.

Smtp:Port

The port of the SMTP server.

Smtp:UserName

The user name used to authenticate with the SMTP server. If not specified, anonymous authentication will be attempted.

Smtp:Password

The password used to authenticate with the SMTP server. The password should not be stored here. Instead, set an environment variable named Smtp__Password.

Smtp:EnableSsl

Set to true to enable SSL.

Smtp:ReplyTo

The email address to use as the sender.

Smtp:DisableCertificateRevocationCheck

Set to true to disable certificate revocation checks.

Smtp:DisableCertificateValidation

Set to true to disable certificate validation.

Home Page Configuration

To show topics on the home page, add the following configuration items.

Home:TopicalConceptSystem:Agency

The agency identifier of the Concept System to display on the home page.

Home:TopicalConceptSystem:Identifier

The unique identifier of the Concept System to display on the home page.

Elasticsearch Configuration

Elasticsearch can be used for the web portal’s search page.

Elasticsearch:Enabled

Set to true to enable Elasticsearch for the the portal search page. Set to false to use the built-in database search.

Elasticsearch:Host

The hostname and port used to access the Elasticsearch server (e.g., http://localhost:9200). If left blank, Elasticsearch will not be used.

Elasticsearch:IndexName

The prefix of the Elasticsearch index. The index name will be {prefix}_registered_item.

Elasticsearch:EnableApiVersioningHeader

Set to true to enable the API versioning header in Elasticsearch requests. This allows using newer versions of the Elasticsearch API.

Logging Configuration

Logging:LogLevel

The level of ASP.NET Core log messages to be included. Options are Error, Warning, Information, Debug.

Serilog:LogLevel

The level of Colectica Repository messages to be included. Options are Error, Warning, Information, Debug, Verbose.

Serilog:Location

The path on disk at which Colectica Repository log files will be stored.

Serilog:StructuredDiskLocation

If specified, the path on disk at which JSON structured log files will be stored. These files can be aggregated by logstash or other systems.

Serilog:HttpLocation

If specified, the URL to which structured logs will be POSTed. This can be used to send logs to logstash or other log aggregation systems.

Repository Settings

Features

RepositorySettings:Features:EnableSchemaValidation

If true, validation items against the format’s XML schema, and fail with error code R0023 if not valid.

RepositorySettings:Features:EnableItemReferenceValidation

If true, validate that any items referenced by the item being registered exist in the repository.

RepositorySettings:Features:SynchronizeExternalRoles

If true, set user roles provided via OpenIDConnect or Azure AD to the internal roles store.

HTTP

Features:Http:CspEnable

Indicates whether Content Security Policy (CSP) is enabled. Set to true to enable CSP.

Features:Http:CspHeader

Specifies the Content Security Policy header value. Example: default-src 'self'; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; object-src 'none'.

Features:Http:XFrameOptionsEnable

Indicates whether the X-Frame-Options header is enabled. Set to true to enable the X-Frame-Options header.

Features:Http:XFrameOptions

Specifies the value for the X-Frame-Options header. Example: SAMEORIGIN.

Features:Http:XContentTypeOptionsEnable

Indicates whether the X-Content-Type-Options header is enabled. Set to true to enable the X-Content-Type-Options header.

Features:Http:HttpsRedirectEnable

Indicates whether HTTP requests should be redirected to HTTPS. Set to true to enable HTTPS redirection.

Features:Http:HttpsRedirectPort

Specifies the port to which HTTP requests should be redirected. Set to 443 for standard HTTPS redirection.

Features:Http:StrictTransportSecurityEnable

Indicates whether HTTP Strict Transport Security (HSTS) is enabled. Set to true to enable HSTS.

Features:Http:StrictTransportSecurityMaxAge

Specifies the max-age directive for HSTS in seconds. Set to 31536000 (1 year) to enforce HSTS for one year.

Features:Http:StrictTransportSecurityIncludeSubDomains

Indicates whether the HSTS policy applies to subdomains. Set to true to include subdomains in the HSTS policy.

Features:Http:StrictTransportSecurityIncludePreload

Indicates whether the HSTS policy includes the preload directive. Set to false to exclude the preload directive.

Features:Http:ReferrerPolicyEnabled

Indicates whether the Referrer-Policy header is enabled. Set to true to enable the Referrer-Policy header.

Features:Http:ReferrerPolicy

Specifies the value for the Referrer-Policy header. Example: strict-origin-when-cross-origin.

Features:Http:SetHostCookiePrefix

Indicates whether to set the host cookie prefix. Set to false to disable the host cookie prefix.

Portal

Features:Portal:DisplayVersionResponsibility

Indicates whether the version responsibility should be displayed. Version responsibility may include identifying information such as email addresses. Set to false to hide the version responsibility.

Features:Portal:DisplayVersionRationale

Indicates whether the version rationale should be displayed. Version rationale may include information about the changes made in a version as recorded in the log message when items are registered with the repository. Set to false to hide the version rationale.

Features:Portal:DisableSwaggerUI

Indicates whether the Swagger documentation for the included REST API should be disabled. Set to false to enable the Swagger UI.

Features:Portal:CollapseQuestionResponseDomainsInFlowchart

Indicates whether question response domains should be collapsed in the flowchart. Set to false to keep the response domains expanded.

Features:Portal:QuestionGridDisplayStyle

Specifies the display style for the question grid. Possible values are Linear and NonLinear. Set to Linear to display simple lists of dimensions and measures. Set to NonLinear to display the question grid in a table.

Features:Portal:AllowAdditionalTagsOnCustomPages

Specifies additional HTML tags that are allowed on custom pages. By default, many tags are stripped from custom pages to prevent security vulnerabilities. Set to an empty array [] to disallow additional tags.

HealthChecks

Features:HealthChecks:MinimumFreeDiskCacheMegabytes

Specifies the minimum amount of free disk space (in megabytes) required for the cache. Set to 500 to require at least 500 MB of free disk space for the cache.

Features:HealthChecks:MinimumFreeDiskLogMegabytes

Specifies the minimum amount of free disk space (in megabytes) required for logs. Set to 250 to require at least 250 MB of free disk space for logs.

General

Features:RepositorySecurityMode

Specifies the security mode for the repository. Possible values are Disabled, Permissive, and Enforcing. Set to None to disable security features. Set to Permissive to allow any user to perform operations that are normally restricted to certain roles. Set to Enforcing to enable normal security features.

Features:CommandTimeoutInSeconds

Specifies the timeout for database commands in seconds. Set to 30 to allow commands to run for up to 30 seconds.

Workflow Configuration

Colectica Repository can be configured to connect to Colectica Workflow Services.

Workflow:Enabled

Indicates whether the workflow functionality is enabled. Set to false to disable workflow functionality.

Workflow:WorkflowServer

Specifies the URL of the workflow server.

Workflow:ServerId

Specifies the server ID for the workflow server. Each repository connected to a workflow server should have a unique server ID. Example: ColecticaRepositoryPublic.

Workflow:ApiKey

Specifies the API key used to authenticate with the workflow server. The API key must be a string that is at least 16 characters long.

Workflow:UseWindowsAuthentication

Indicates whether to use Windows authentication for the workflow server. Set to false to disable Windows authentication.

Workflow Preview Configuration

Colectica Repository can be deployed with a workflow preview feature that allows users to preview the results of workflow replications before approving them.

WorkflowPreview:IsWorkflowPreview

Indicates whether the workflow preview functionality is enabled. Set to false to disable workflow preview functionality.

WorkflowPreview:WorkflowPreviewFilePath

Specifies the file path for storing workflow preview databases.

File Storage Configuration

FileStorage:Enabled

Indicates whether file storage is enabled. Set to true to enable file storage functionality.

FileStorage:StorageType

Specifies the type of storage to use. Possible values are LocalDisk and WebDAV.

FileStorage:MaxUploadSize

Specifies the maximum upload size in bytes. Set to 104857601 to allow uploads up to approximately 100 MB.

FileStorage:LocalDisk:StoragePath

Specifies the path on the local disk where files will be stored.

FileStorage:WebDAV:StorageUri

Specifies the URI of the WebDAV storage.

FileStorage:WebDAV:Username

Specifies the username for accessing the WebDAV storage. Set to the appropriate username for authentication.

FileStorage:WebDAV:Password

Specifies the password for accessing the WebDAV storage. Set to the appropriate password for authentication.

OpenTelemetry Configuration

To use OpenTelemetry for monitoring and tracing, configure the following settings. Additionally, the standard environmental variables need to be set for OpenTelemetry to work. For more information, refer to the OpenTelemetry documentation: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/

OpenTelemetry:Enabled

Indicates whether OpenTelemetry is enabled. Set to false to disable OpenTelemetry functionality.

Miscellaneous Configuration

SupportedLanguages

A list of languages supported by the user interface. By default this is "en-US", "fr", "fr-CA". To add support for additional languages, see Localization, and then update this property.

Language

The default language of the user interface. Built-in options are en-US, fr, fr-CA.

ForwardedHeadersEnabled

Enable inspection of X-Forwarded-* headers for use behind an HTTP proxy or load balancer.

XForwardedForDisabled

Disable inspection of the X-Forwarded-For header.

DefaultAdminUser

If set, the specified user will be granted administrator privileges.

DefaultNewUserRole

If set, the specified role will be added to new user registrations and external logins.

Admin:ExternalDashboardUrl

The URL of an external dashboard. If set, a button linking to the URL will be included in the Colectica Portal administrator dashboard.

EntityFramework:ApplicationDbContext:ConnectionStringKey

Used by ASP.NET core. This value should not be changed.

Open ID Connect Configuration

OpenIDConnect:*

See Configure OAuth2 OpenID Connect (OIDC) for details.

Local JWT Token Configuration

LocalJwtProvider:*

See Configure Local JWT Token Provider (Optional) for details.

Identity Password Policies

When using database-managed user accounts, the following settings can be used to configure password policies.

IdentityPasswordPolicy:RequireDigit

Indicates whether a password must contain at least one numeric digit (0-9). Set to true to enforce this requirement.

IdentityPasswordPolicy:RequireLowercase

Indicates whether a password must contain at least one lowercase letter (a-z). Set to true to enforce this requirement.

IdentityPasswordPolicy:RequireUppercase

Indicates whether a password must contain at least one uppercase letter (A-Z). Set to true to enforce this requirement.

IdentityPasswordPolicy:RequireNonAlphanumeric

Indicates whether a password must contain at least one non-alphanumeric character (e.g., !, @, #). Set to false to disable this requirement.

IdentityPasswordPolicy:RequiredLength

Specifies the minimum length of a password. Set to 6 to require passwords to be at least 6 characters long.

IdentityPasswordPolicy:RequiredUniqueChars

Specifies the minimum number of unique characters that a password must contain.

API Configuration

API:EnableRESTv1

Set to true to enable the REST API.

Concordance Configuration

Concordance tables show the relationships among variables across time and across studies. Variables can be visually grouped based on how they are organized in your metadata.

Concordance:GroupVariablesByPhysicalInstances

Whether to show concordance tables with variables grouped by dataset descriptions.

Concordance:GroupVariablesBySchemes

Whether to show concordance tables with variables grouped by variable sets.

See also

See Data Concordance for more information on concordance views.

By default, the concordance tables in the Explore views are constructed for items under a single Series. When a single series is appropriate, no additional configuration is required. To enable concordance tables to be constructed for multiple series, the order of the series must be specified in the appsettings.json file. The ordered list of series is specified for each Concept Set. A sample configuration looks like this:

"Explore": {
  "Views": [
    {
      "ConceptSchemeAgency": "int.example",
      "ConceptSchemeId": "8a3e03ac-4ff3-4043-b997-96847e0c86fb",
      "GroupIdentifiers": [
        {
          "Agency": "int.example",
          "Id": "fab89d2e-030e-4a22-b67c-1e0762577d58"
        },
        {
          "Agency": "int.example",
          "Id": "502aac29-f6db-4b64-a6d2-92b72f7f8e4d"
        },
        {
          "Agency": "int.example",
          "Id": "9b2cd493-073a-4128-8b5b-530a3eb67481"
        }
      ]
    }
  ]
}

Sample Database Connection Strings

The Colectica Repository makes use of two databases per installation, one database to store the metadata content and another that is used by the web portal. You may use whatever name you wish for the databases, by default the documentation refers to them as the colectica and colectica-portal databases.

Ensure that the database account has permissions to create and modify tables and schemas within the database. The database creation is detailed in the next step.

SQL Server

"DefaultConnection": {
  "ConnectionString": "Server=.;Initial Catalog=colectica-portal;Trusted_Connection=True;MultipleActiveResultSets=true",
  "ProviderName": "System.Data.SqlClient"
},
"ColecticaRepository": {
  "ConnectionString": "Server=.; Initial Catalog=colectica; Integrated Security=SSPI;",
  "ProviderName": "System.Data.SqlClient"
}

PostgreSQL (v5.3.6233 and later)

"DefaultConnection": {
  "ConnectionString": "Host=localhost;Database=colectica-portal;Username=postgres;Password=Postgres1234;",
  "ProviderName": "Npgsql"
},
"ColecticaRepository": {
  "ConnectionString": "Host=localhost;Database=colectica;Username=postgres;Password=Postgres1234;",
  "ProviderName": "Npgsql"
}

PostgreSQL (Prior to v5.3.6233)

Note

The Postgres provider changed User ID to username in a later release.

"DefaultConnection": {
  "ConnectionString": "User ID=postgres;Password=Postgres1234;Host=localhost;Port=5432;Database=colectica-portal;",
  "ProviderName": "Npgsql"
},
"ColecticaRepository": {
  "ConnectionString": "User ID=postgres;Password=Postgres1234;Host=localhost;Port=5432;Database=colectica;",
  "ProviderName": "Npgsql"
}