appsettings.json¶

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

Navigate to RepositoryDir/.
If there is not a file named appsettings.json, then copy the appsettings.json.dist file to appsettings.json.
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.

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

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"
}