> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/assistant/shell/creating-a-shell.md). # Creating a Shell ## Overview Creating a Shell involves two steps: preparing your service for upload to Spark (see [Mapper](/assistant/mapper/mapping-inputs-and-outputs.md)), and configuring your Shell file Operator experience. Shell creation is managed entirely in your source file via the Coherent Assistant Add-in. ## Navigating to the Shell Creator Screen You can begin creating your Shell by navigating to the "Shell" application in Coherent Assistant (shown in the screenshot below). Please note that Shells can only be created through this application - using the "Upload" application will not create a Spark Shell.

Coherent Assistant Homepage

## Shell Creator If your source file does not have an existing Shell associated with it in your tenant, then opening the Shell application will take you into the Shell Creator experience (note that files with Shells already associated with them will show a different experience - see [Managing Shell files](/assistant/shell/managing-shell-files.md) for more information). The Shell Creator Experience contains components to help prepare your file for Spark upload, configure your Shell, upload to Spark, and create your Shell file for Shell Operators.

Shell Creator experience

### Mapper Integration Shell Creator contains an integration with [Mapper](/assistant/mapper/mapping-inputs-and-outputs.md) to add, view, edit, or remove inputs/outputs for your Shell file, allowing you to seamlessly map your file in the context of creating your Shell. Note that you must map your file in order to create your Shell - the "Create Shell" button will be disabled until the file is mapped. ### Configure Settings Users can configure settings for user experience, security, and logging/data submission handling. These settings are configurable at the service and version level if you will be managing multiple Shells or multiple versions of a Shell. Shell configuration settings provide instructions to creators to guide users on how to use Shell configurations. #### Included Sheets Hiding sheets or deselecting a sheet in the "Included Sheets" configuration will remove the sheet from your created Shell file. This will not remove the sheet from your existing source file, nor will it impact any calculations dependent on any removed Sheets. This feature allows you to control what users see in the created Shell file, obfuscate any sensitive business logic, and improve performance of your Shell by maintaining only the formulas/outputs users need to see to operate the Shell. For optimal performance, it is recommended that all content not required to operate the Shell is removed. The "Included Sheets" screen will only include sheets that are not hidden in the list of sheets - as hidden sheets are automatically removed from created Shell files. If you wish to include a currently hidden sheet in your created Shell file, unhide it to make it visible in your Shell. Sheets containing inputs will be flagged in this screen to notify users which sheets contain fields operators may need to edit to use the Shell file.

Select your included sheets

#### Shell Protection/Security Settings Users can set configurations for workbook protection, password, and service authentication requirements as part of Shell creation, depending on protection requirements. **Require Login** configures the authentication requirements for the Spark service contained in your Shell. Checking this configuration will require users to authenticate via Coherent Assistant into the tenant containing the service in order to use the Shell. If this configuration is set, Shell users must have Spark credentials to the associated tenant, and permissions to execute the associated service. If configuration is not selected, Shell users will not need to authenticate to use the Shell file - Operators will not require Spark credentials to use the Shell. Please note that if your tenant is not configured to enable Public API for Spark Shell, Shell creators will only be able to configure Shells to Require Login. **Protect Shell** applies protection to any formulas, outputs, static (non-Input) values in your created Shell file, providing protection against changes to the file by Operators. If a user attempts to edit or delete a protected cell, they will see an Excel error notifying them that they cannot edit a protected cell. Mapped Inputs and blank cells are still editable (not protected) to allow for workbook usability. Please note that if your file contains any previously configured allowed edit ranges, these cells will not be protected by Shell - to enable protection on any of these cells, go to Review -> Allow Edit Ranges in Excel and remove any ranges from the list that you wish to protect in your Shell file. **Add Password** allows users to require a password for users to unprotect a sheet or the workbook, adding additional protection against workbook changes. This password is set by the user during configuration. Note that this password applies to structural changes to the workbook and unprotecting cells only - this does not add a password protection to opening the file.

Shell Protection/Security Configurations

#### Customize Shell Users can further customize Shell user experience and data submission functionality by choosing to include instructions and/or a submit button to their Shell file. **Instructions** allow users to set custom instructions, contact information, or usage information for their Shell to provide helpful context on how to operate the Shell file. This text will appear on the Add-in pane of the Shell file when Operators use it. The **Submit Button** configuration enables a button on the Add-in pane of the Shell file that records a "submit" event for the Shell file. Shell files will recalculate similar to an Excel file as Operators edit inputs, and create a log in Spark (if logs are enabled in your Spark service/tenant), but using the Submit button allows Creators to have data from the Shell inputs/outputs be sent to the Business Event Log, a user-configured endpoint (Such as a system of record), and/or be flagged in the API Call History with a designated `call_purpose`. This provides an interface where Operators can submit "final submissions" while using their Shells if required as part of your process. The text of your submti button is customizable. Before creating your Shell, you can preview how your Shell will look to an Operator using the "Preview" button.

Customize your Shell with instructions or a submit button

Customize your submit button

Customize your Shell instructions

Preview what Operators will see in the Add-in

### Create Shell After configuring your Shell, clicking the "Create Shell button will take you to an integration with the upload journey to upload your workbook to Spark. The service created will power your Shell file. See [Creating a new service](/assistant/services/creating-a-new-service.md)for more information. Once you publish your Shell service, your Shell file will open in a new Excel window, and you will be notified to save the file. Coherent Assistant will automatically open in this file - when you see the below message, click "Continue", and your Shell will be ready to deploy to Shell Operators.

Click Continue to finalize your Shell file.

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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.coherent.global/assistant/shell/creating-a-shell.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.