# Isabl Settings Each component of Isabl can be configured in multiple ways. Generally, settings are strings, numbers, objects, and many other types. {% hint style="info" %} **`Import Strings`** point to an *importable* object, whether its a class, a function, etc. (e.g.`isabl_cli.data.DataImporter`) {% endhint %} ## Database Managed Settings Some Isabl API, Isabl Web, and Isabl CLI and be configured from the admin site! To do so, go to `/admin/isabl_api/client/` and update the clients called `default-backend-settings` for Isabl API, and `default-frontend-settings` for Isabl Web. You may want to create your own client for Isabl CLI (see [Writing Applications](/writing-applications.md)). ## Isabl API Settings Here is a detailed list of available configurations for Isabl API. To configure Isabl API, add a dictionary called `ISABL_SETTINGS` to your Django configuration. | Setting Name | Type | Description | | ---------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **EXTRA\_GENDERS** | *List* | `Individual genders` as two-value tuples (value, verbose name). | | **EXTRA\_STATUS** | *List* | `Analysis status` as two-value tuples (value, verbose name). | | **EXTRA\_RAW\_DATA\_FORMATS** | *List* | Experiment `raw_data` formats as two-value tuples (value, verbose name). Learn how to support extra formats [here](/import-data.md#supported-data-formats). | | **EXTRA\_SPECIES** | *List* | Individual `species` as three-value tuples (value, verbose name, system\_id modifier). For example: `[("YEAST", "YEAST", "Y")]` | | **EXTRA\_SAMPLE\_CATEGORIES** | *List* | Sample `categories` as three-value tuples (value, verbose name, system\_id modifier). For example`[("UNKNOWN", "UNKNOWN", "U")]` | | **EXTRA\_TECHNIQUE\_METHODS** | *List* | Technique `methods`as three-value tuples (value, verbose name, system\_id modifier). For example:`[("SINGLE-CELL RNA", "SINGLE-CELL RNA", "scRNA")]` | | **API\_V1\_EXTRA\_PATTERNS** | *Import String* | Import path to a list of [`urlpatterns`](https://docs.djangoproject.com/en/2.2/ref/urls/)to append to API v1. | | **SYSTEM\_ID\_PREFIX** | *String* | A prefix for the default sample ID generated by Isabl (with the hope to differentiate objects across Isabl instances). For example, if set to `DEMO`, then experiments might be named `DEMO_H000002_T01_01_TD01`. | | **SYSTEM\_ID\_GENERATOR** | *Import String* | Import path to a function that takes either an `Individual`, `Sample`, `Aliquot`, or `Experiment` and returns a system identifier. This will overwrite the default generation of system ids (e.g. `DEMO_H000002_T01_01_TD01`). | | **FRONTEND\_URL** | *String* | URL where the frontend is being deployed (not required if frontend running in same host as backend). | | **JIRA\_SETTINGS** | *Dictionary* | Feature to integrate JIRA with Isabl projects (It can assign a different JIRA epic to each Isabl Group). [See more](/isabl-settings.md#integrating-with-jira). | | **REQUIRE\_ACCOUNT\_APPROVAL** | *Boolean* | Disable new accounts and send out email to admins to require approval before new users can login. | | **S3\_BASE\_STORAGE\_DIRECTORIES** | *Dictionary* | Support loading analyses results from a AWS s3 based "BASE\_STORAGE\_DIRECTORY". Learn more [here](/isabl-settings.md#loading-results-from-a-aws-s3-bucket). | Learn more about production deployment: {% content-ref url="/pages/-LgZjrA075oF5YZLVGsU" %} [Production Deployment](/production-deployment.md) {% endcontent-ref %} ### Loading results from a AWS S3 bucket If your Isabl CLI [**`BASE_STORAGE_DIRECTORY`**](/isabl-settings.md#isabl-cli-settings) is located in a S3 bucket, you can enable rendering results through the website using the **`S3_BASE_STORAGE_DIRECTORIES`** setting**:** ```python "S3_BASE_STORAGE_DIRECTORIES": { "/base/path/in/output-file": { "bucket": "an-S3-bucket-name", "access_key": "The AWS Access Key", "access_key": "The AWS Access Key", "base_directory": "/base/path/in/s3/object", "prefer_original": false } } ``` For example if an analysis output path is `/mnt/data/analyses/01/01/1/head_job.log` and and the s3 path to it is `s3://my-bucket/data/analyses/01/01/1/head_job.log` you should use this setting: ```python "S3_BASE_STORAGE_DIRECTORIES": { "/mnt/data/": { "bucket": "my-bucket", "base_directory": "/data/", ... } } ``` if `prefer_original` is set to `True` (`False` by default), it will try to retrieve the original path first if exists (i.e. `/mnt/data/analyses/01/01/1/head_job.log`) , if not it will try to resolve for the file in S3 (i.e. `s3://my-bucket/data/analyses/01/01/1/head_job.log`) ### Integrating with Jira Isabl provides a simple integration to [Jira](https://www.atlassian.com/software/jira/guides/use-cases/what-is-jira-used-for), as it's a widely used management tool used for development and analyses. The module creates a *Jira Epic* for each Isabl project, and allows to create a simple list of tasks (*Jira issues*) from the web. ![Jira Integration Demo](/files/-MRgh89mUx9bNFgMO_sN) To enable, you need to add the following settings in the web and in the api. **In the Web Settings:** {% code title="index.html" %} ```javascript window.$isabl = { ... jira: true } ``` {% endcode %} **In the Api Settings:** In Jira for Epic and Issues we can [create custom fields](https://confluence.atlassian.com/adminjiraserver/adding-a-custom-field-938847222.html). You need to create 2 custom fields where the Project ID and the Project Link will be stored, and use their ids in the settings. ```python "JIRA_SETTINGS": { "active": True, "default": { "URL": "https://my-jira-instance", "AUTH": ("jira-username", "secret-jira-password"), "PROJECT_KEY": "ISABL", "URL_FIELD": "customfield_id_1", "PROJECT_FIELD": "customfield_id_2", } }, ``` {% hint style="success" %} ***Pro Tip:** Jira Epics* are created under *Jira Projects. Y*ou can create different Jira Projects for each Isabl Project Group, by adding extra dictionaries that map to isabl group acronyms. i.e. If a group in Isabl is called (name: Pathology, acronym: PATH), you can set up your settings like the example below. And all Isabl Projects that belong to the PATHOLOGY group, will have their own separate Jira Project under `https://my-jira-instance/projects/PATH/issues/` ```python "JIRA_SETTINGS": { "active": True, "default": { "URL": "https://my-jira-instance", "AUTH": ("jira-username", "secret-jira-password"), "PROJECT_KEY": "ISABL", "URL_FIELD": "customfield_id_1", "PROJECT_FIELD": "customfield_id_2", }, "PATH": { "URL": "https://my-jira-instance", "AUTH": ("jira-username", "secret-jira-password"), "PROJECT_KEY": "PATH", "URL_FIELD": "customfield_id_1", "PROJECT_FIELD": "customfield_id_2", } }, ``` {% endhint %} ## Isabl CLI Settings Before anything, you must set the following environment variables: ```bash # you need to let Isabl CLI where the API is being hosted export ISABL_API_URL='your-isabl-instance.org/api/v1/' # you can create a client object in from the django admin export ISABL_CLIENT_ID= ``` Once this is set, you can configure your client object settings with the following configurations (see [**`isabl_cli.settings`**](https://github.com/isabl-io/cli/blob/master/isabl_cli/settings.py#L20) to check default settings):
Setting NameTypeDescription
Setting NameTypeDescription
API_BASE_URLStringurl host where your isabl api is running. Needed to connect the CLI with the API.
BASE_STORAGE_DIRECTORYStringDirectory where data will be store in the file system.
TIME_ZONEStringCurrent timezone used by pytz package.
INSTALLED_APPLICATIONSImport Strings ArrayArray of registered applications to be run with the cli tool. These apps can be seen and run isabl apps --help.
CUSTOM_COMMANDSImport Strings ArrayArray of custom commands to be added to the custom cli tool.
SYSTEM_COMMANDSImport Strings ArrayArray of system commands that are used in isabl-cli.
ADMIN_COMMANDSImport Strings ArrayArray of commands that are only executable by admin.
ADMIN_USERStringLinux user for which admin operations will be limited. This user will own the data and analyses results. Nevertheless, Isabl Applications can be run by multiple unix users. Learn more about it here.
CREATE_SYMLINKSBooleanBy default, Isabl creates a symlink farm upon data import and analyses completion. You can turn it off with this setting.
DEFAULT_LINUX_GROUPStringLinux group for data admin_user to use.
MAKE_STORAGE_DIRECTORYImport StringGet and create path to a data directory.
TRASH_ANALYSIS_STORAGEImport StringMove analysis storage_url to a trash directory.
REFERENCE_DATA_IMPORTERImport StringRegister input_bed_path in technique's storage dir and update data.
DATA_IMPORTERImport StringImport raw data for multiple experiments.
BED_IMPORTERImport StringRegister input_bed_path in technique's storage dir and update data.
ON_DATA_IMPORTImport Strings ArrayMethods triggered when data has been imported successfully.
ON_STATUS_CHANGEImport Strings ArrayMethods triggered when an analysis changes status.
ON_SIGNAL_FAILUREImport Strings ArrayMethods triggered when an signal fails.
SUBMIT_ANALYSESImport StringA function that will take a list tuples (analysis, path to analysis script) and submits them to a given compute architecture.
SUBMIT_CONFIGURATIONDictionaryA schema-less dictionary to set configurations that the SUBMIT_ANALYSES function may utilize. See more Batch Systems.
EXTRA_RAW_DATA_FORMATSTuples ArrayFor every new supported format a tuple of (regex validator, file_data_type) i.e. To support Illumina ORA format: ["\\.ora?$", "ORA"]
{% content-ref url="/pages/-LgZjlyvKfTRM6B0HnMl" %} [Writing Applications](/writing-applications.md) {% endcontent-ref %} #### Submit Configuration ## Isabl Web Settings Customization of the User Interface can be achieved by defining a global `$isabl` settings dictionary in the main `index.html`. ```markup ``` You can configure the `window.$isabl` with the following parameters:
Setting NameTypeDefaultDescription
Setting NameTypeDefaultDescription
apiHostString''Url host where your isabl api is running.
nameString'isabl'Custom app title that is shown in the top of the app.
logoStringCustom image path that is shown as the main logo of the app. Use a square size image for better display.
jiraBooleanfalseActivate the jira card in the projects view. If the jira endpoint is available from the api, it will show the current tickets for each project. Learn more about jira integration.
oncoTreeBooleanfalseIf it's enabled, more information about the onco tree disease is added in the Sample details.
customFieldsObject{}Every detail info for each model shown in the frontend can be customized, by overwriting the specific key of a fields object. Available fields can be seen here. Learn more on how to create custom fields (TODO).
restartButtonBooleanfalseIf enabled,FAILED analyses can send a signal to restart or force to the database. Learn more in signals.
lightThemeObjectSee defaultsColors to customize the light theme.
darkThemeObjectSee defaultsColors to customize the dark theme.
modelIconsObject{}Material Icon names to customize panel icons.
distinctRecordsBooleanfalseBy default, api queries don't remove duplicates as it impacts speed. Set true to avoid duplicate records.
treeIconsObject{}

Please use these if the graph icons are broken:

"treeIcons": {
    "male": "https://isabl-web.s3.us-east-1.amazonaws.com/male.svg",
    "female": "https://isabl-web.s3.us-east-1.amazonaws.com/female.svg",
    "normal": "https://isabl-web.s3.us-east-1.amazonaws.com/normal.svg",
    "tumor": "https://isabl-web.s3.us-east-1.amazonaws.com/tumor.png",
    "aliquot": "https://isabl-web.s3.us-east-1.amazonaws.com/normal.svg",
    "dna": "https://isabl-web.s3.us-east-1.amazonaws.com/dna.svg",
    "rna": "https://isabl-web.s3.us-east-1.amazonaws.com/rna.svg",
    "mouse": "https://isabl-web.s3.us-east-1.amazonaws.com/mouse.svg",
    "image": "https://isabl-web.s3.us-east-1.amazonaws.com/image.svg",
    "alien": "https://isabl-web.s3.us-east-1.amazonaws.com/unknown.svg",
  }
### Example of a custom UI configuration ```markup ``` {% hint style="warning" %} **Important:** In case you're running your frontend instance in a different host that the backend, you should add this `ENV` variable to your django project where the `isabl-api` is running: ```bash export FRONTEND_URL="http://your-frontend-host.com" ``` {% endhint %} {% hint style="success" %} If you want to consume `isabl-web` and serve your own html, outside of `isabl-api`. You can consume the frontend just as: {% code title="index.html" %} ```markup My Awesome App
``` {% endcode %} {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.isabl.io/isabl-settings.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.