# Overview Extend the capabilities of Excel and simplify your workflow Coherent Assistant is an Excel add-in designed to integrate the capabilities of Spark directly into Excel. It enables users to connect to their Spark instance, upload and download Spark services as Excel files, and create testbeds within Excel. Additionally, users can establish live connections to external APIs and Spark services directly from Excel, among many other features. The add-in can be installed from Microsoft AppSource Marketplace or with a manifest file. Follow the steps in [Installation](/assistant/get-started/installation) to have the add-in appear in Excel. ## Applications Coherent Assistant offers a suite of applications designed to enhance your daily workflow. Below, you will find a list of these applications accompanied by brief descriptions of their functionalities. We are committed to continuously expanding this suite with new applications and enhancing the features of existing ones.


Connect	Establish a direct connection to Spark to unlock features that seamlessly integrate with Spark.	/files/qXH1jxQKFGOWedMl5PV4	/pages/YOBRoAtAJyw2TCVkEDPU
Agent	Use AI to understand, audit, and update workbooks with guided approvals.	/files/dceh9jV7sypFO3P8dQAP	/pages/hxfuuAtg9lKPcCGIph7e
Mapper	Mapping the inputs and outputs of your model is now easier than ever.	/files/lnTWLn6AudxNo4UYJhe1	/pages/t3UOrlLIB19R8PCVQJ6f
Services	Browse, create, and update Spark services directly from Excel.	/files/2m3sH9lnfrqtlD9dCGFM	/pages/GHFoSeYaqfvvlfyk2YAl
Solver	Performs a What-if analysis similar to Goal Seek with each API call.	/files/oMuvXpKMQZApoFWgjGGa	/pages/VMTCL70F0Gqt2Pu8koUM
Shell	Obfuscate the logic of your Excel models to simplify collaboration.	/files/Vf2CLyn0ugRXayELpU8x	/pages/nXp1U0dJdrVPKVtPan8U

# Installation The Coherent Assistant can be installed via different methods. Choose the approach that works best for your organization. The Coherent Assistant is developed using [Office JavaScript](https://learn.microsoft.com/en-us/office/dev/add-ins/develop/understanding-the-javascript-api-for-office). Relevant documentation to understand more about Office Add-ins are linked below: * [Office Add-ins documentation](https://learn.microsoft.com/en-us/office/dev/add-ins/). * [Develop Office Add-ins](https://learn.microsoft.com/en-us/office/dev/add-ins/develop/develop-overview). * [Privacy and security for Office Add-ins](https://learn.microsoft.com/en-us/office/dev/add-ins/concepts/privacy-and-security). * [Addressing end users' privacy concerns](https://learn.microsoft.com/en-us/office/dev/add-ins/concepts/privacy-and-security?tabs=jsonmanifest#addressing-end-users-privacy-concerns). ## Install Office Add-in from Excel This is the easiest method to install Coherent Assistant if you have Microsoft 365 and is permitted by your organization. In Excel, from the **Home** ribbon then click **Add-Ins**. Search for Coherent Assistant and install. For more detailed instructions, follow the documentation from Microsoft in [View, manage, and install add-ins for Excel, PowerPoint, and Word](https://support.microsoft.com/en-us/office/view-manage-and-install-add-ins-for-excel-powerpoint-and-word-16278816-1948-4028-91e5-76dca5380f8d). ## Deploy from the Microsoft 365 admin center This is the recommended method to install Coherent Assistant for organizations that prevent users from installing their own add-ins. This needs to be done by a Microsoft 365 administrator. Follow the documentation from Microsoft. From the AppSource store, look for Coherent Assistant. * [Determine if centralized deployment of Office Add-ins works for your organization](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/centralized-deployment-of-add-ins). * [Deploy add-ins in the Microsoft 365 admin center](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-deployment-of-add-ins). ## Sideload Office Add-in This is an alternative method of installing Office Add-Ins using sideloading. This approach can be used for testing or limited unmanaged installations. If Coherent updates the manifest file, then this process may to be repeated for the updated file. Request the Coherent Assistant manifest from [Support](/support/faq) and follow the documentation from Microsoft. * [Test Office Add-Ins](https://learn.microsoft.com/en-us/office/dev/add-ins/testing/test-debug-office-add-ins). * Excel on the web: [Manually sideload an add-in to Office on the web](https://learn.microsoft.com/en-us/office/dev/add-ins/testing/sideload-office-add-ins-for-testing#manually-sideload-an-add-in-to-office-on-the-web). * Windows applications: [Sideload Office Add-ins for testing from a network share](https://learn.microsoft.com/en-us/office/dev/add-ins/testing/create-a-network-shared-folder-catalog-for-task-pane-and-content-add-ins). {% file src="/files/0tkrKXGrsamNEd5036Nj" %} # Connect to Spark Once Coherent Assistant has been installed, you can use some of the functionality without logging into your Spark account. But most of the features are only available once you are logged in. ## Connect to Spark

1. Open Coherent Assistant and click on the bars

to open the sidebar. 2. Click on **Login** on the sidebar. 3. Enter your Spark login URL into the text field. Click on **Connect to Spark**. 4. On the login window that opens, enter your credentials and click **Log in.**

Login modal that opens once you click on Connect to Spark.

{% hint style="info" %} You can use the same account that you use to access Coherent Spark. The Coherent Assistant uses the same means of authentication to our Software as a Service (SaaS) offering. {% endhint %} ### Where is my Spark URL? Spark URL is the domain you use to reach Spark on the Web (can also use any URL from Spark once you've logged in) or the endpoint URL of any service you have on Spark. {% hint style="info" %} The Spark URL has the following syntax: `https://spark.[environment].[region].coherent.global/[tenant]` {% endhint %} ### I am getting an error: Invalid parameter, redirect\_uri This error occurs when attempting to connect to a Spark environment not supported by Coherent Assistant. Please ensure you are using either UAT or PROD environments to log in. # What is Agent? Agent is an AI assistant built into Coherent Assistant for Excel. It helps you understand workbooks, explain formulas, analyze data, create pivot tables, compare files, and complete everyday Excel tasks without leaving Excel.

Agent working beside a spreadsheet workbook — Agent works beside your workbook to help explain, review, compare, and improve spreadsheet content.

Agent works beside your workbook. It can use the active sheet, selected cells, attached files, saved outputs, and the conversation so far to answer questions or complete a task. When a request needs more information, Agent asks a follow-up question. When a request would change workbook content, Agent can ask for approval before it acts. ## What Agent is good for Use Agent when you want to move from a workbook question to a practical next step. For example, Agent can help you: * Understand how a workbook is organized and what each sheet is for. * Explain formulas, assumptions, outputs, and calculation flow. * Summarize sheets, ranges, tables, and attached data files. * Find hardcoded values, inconsistent formulas, errors, external links, and other review signals. * Update values, formulas, formatting, sheets, and ranges after you approve the change. * Create, refresh, and adjust pivot tables. * Compare workbook versions and summarize material differences. * Use saved instructions for repeated team workflows. Agent is most useful when you give it a clear area to inspect and a clear outcome. Instead of asking it to "analyze everything," start with a workbook, sheet, range, table, or attachment. ## How Agent works with your workbook You chat with Agent in plain language. Agent reads the relevant workbook context from your device, decides what information it needs, and uses AI to produce a response. It does not upload your whole workbook just because you open Agent. Agent can work in different levels of control. In read-only mode, it reviews and explains. In editing modes, it can prepare workbook changes and ask for approval before applying them. This helps you keep review work separate from workbook edits. ## Example requests Try requests like these: * "Summarize the active sheet and identify the main inputs and outputs." * "Find formulas that reference the Assumptions tab." * "Review this workbook for potential model issues and group findings by severity." * "Create a pivot table from the selected range with Region as rows and Revenue as values." * "Compare the attached workbook with the open workbook and list material differences." If Agent's answer is too broad, ask a narrower follow-up. If the task is important, ask Agent to include cell references and assumptions. ## Safety and control Agent is designed to keep you in control. Use read-only mode for review, Ask for edit mode when you want to approve changes, and Agent mode only for trusted tasks with clear instructions. Review important AI outputs before relying on them, especially when they affect formulas, business assumptions, customer communication, or reporting. See [AI Guidelines](/assistant/agent/ai-guidelines) for privacy, data handling, and AI limitations. ## Related pages * [AI Guidelines](/assistant/agent/ai-guidelines) * [Getting started with Agent](/assistant/agent/getting-started-with-agent) * [Chatting with Agent](/assistant/agent/chatting-with-agent) * [Agent modes and approvals](/assistant/agent/agent-modes-and-approvals) * [Using files and attachments](/assistant/agent/using-files-and-attachments) # AI Guidelines {% hint style="info" %} Agent uses AI features that may still be improving. Availability, model options, and usage limits can vary by organization. Contact [Support](/support/faq) if you need help with access, usage limits, or your organization's AI requirements. {% endhint %}

Responsible AI use with Agent — Agent helps you review workbook context with AI while keeping you in control.

Agent helps you work with Excel through natural-language requests. You can ask it to explain formulas, summarize sheets, create analysis, compare files, review workbook risks, and make approved workbook changes. Because Agent uses AI, treat its responses as a helpful assistant's work rather than a final control. Review important outputs, confirm business assumptions, and keep your organization's data rules in mind. ## How Agent uses AI Agent combines workbook context from your device with the instructions you provide in chat. It decides what information is relevant, prepares a focused request, and sends that request to the language model available to your organization. Agent does not upload an entire workbook just because you open Agent. It uses local workbook information, selected ranges, attached files, conversation history, and saved instructions only when they are relevant to your request. ## Good uses for Agent Agent works best when the task has a clear goal and a clear source of context. For example, you can ask Agent to: * Explain the purpose of a workbook, sheet, range, or formula. * Identify key inputs, outputs, assumptions, and calculation flow. * Review formulas for inconsistencies, hardcoded values, external links, or errors. * Summarize table-style data by region, month, customer, product, or status. * Create or adjust workbook content after you approve the change. * Compare workbook versions and summarize material differences. * Use an attached file or knowledge base article as background for a task. For broad work, start with a review request before asking Agent to make changes. A short summary often reveals which follow-up questions are worth asking. ## Write requests that give Agent enough context A strong request tells Agent what to do, where to look, and how to answer. Use this pattern: > Do \[task] using \[sheet, range, workbook, attachment, or article]. Return \[format, level of detail, or decision criteria]. Examples: * "Review `Model!A1:K120` for formula consistency. Return the five highest-priority issues with cell references." * "Summarize the attached workbook for an approver. Focus on assumptions, outputs, and unusual changes." * "Use the selected table to create a revenue summary by month and region. Show the result before editing the workbook." Avoid requests such as "fix this" or "analyze everything." If a request is too broad, Agent may ask a follow-up question or produce a shallow answer. ## Review AI responses before relying on them AI responses can contain mistakes, miss context, or overstate confidence. Review Agent's work before using it for business decisions, customer communication, regulatory reporting, or production workbook changes. For higher-risk tasks: * Ask Agent to show cell references, assumptions, and reasoning in a concise form. * Ask for a preview before workbook edits. * Use read-only mode for review and Ask for edit mode for changes. * Check formulas and outputs after Agent changes a workbook. * Save a copy of important workbooks before major edits. ## Data handling and privacy Agent is designed to use local workbook information first. Conversations, saved outputs, Skills, and temporary files are stored in browser storage on your device. When Agent needs an AI response, it sends only the information needed for that request. The original workbook file is not shared with the AI provider. Agent extracts and sends only the information necessary to perform the requested analysis. Coherent uses OpenAI through API business terms, where customer prompts and outputs are not used to train OpenAI models by default. OpenAI's standard API retention is limited, commonly up to 30 days, and is primarily for abuse monitoring and service operations, after which the data is deleted unless a legal requirement applies. The exact model options and AI provider configuration can vary by organization. Use the settings available to your organization, and contact Support if you need details about your approved configuration. Do not include sensitive information in prompts unless your organization allows that use. If your team has stricter data handling requirements, confirm the approved workflow with your administrator or contact Support. ## Limitations Agent is useful for workbook assistance, but it has practical limits: * Very large workbooks or attachments may take longer to process or may need narrower requests. * Complex tasks may require follow-up prompts, smaller ranges, or separate steps. * AI can misread ambiguous labels, hidden assumptions, or business-specific context. * Agent may ask for approval before workbook changes, especially when existing content could be overwritten. * Some features, model options, and usage limits may differ by organization. ## Related pages * [Getting started with Agent](/assistant/agent/getting-started-with-agent) * [Chatting with Agent](/assistant/agent/chatting-with-agent) * [Agent modes and approvals](/assistant/agent/agent-modes-and-approvals) * [Settings and storage](/assistant/agent/settings-and-storage) # Getting started with Agent Use Agent when you want help understanding, updating, or analyzing an Excel workbook. Agent works best when your request identifies the workbook area to use, the result you want, and any limits Agent should follow.

## Open Agent 1. Open the workbook you want to work with. 2. Open Coherent Assistant in Excel. 3. Select **Agent** from the Coherent Assistant application list. 4. Start a new chat or continue an existing conversation. Before you start, decide whether you want Agent to review information, prepare a change, or make a workbook edit after approval. That choice determines which mode and prompt style to use. ## Start with a specific request A useful first message gives Agent enough context to begin without guessing. Use this pattern: > Do \[task] using \[sheet, range, workbook, or attachment]. Return \[format or level of detail]. Good examples: * "Summarize the active sheet and identify the main inputs, outputs, and assumptions." * "Review the formulas in column G and explain what they calculate." * "Create a monthly revenue summary from the table on the Sales sheet." * "Find hardcoded numbers in this model and tell me which ones look risky." Less helpful examples: * "Fix this." * "Analyze everything." * "Make it better." If the request is broad, Agent may ask a follow-up question. You can save time by naming the sheet, range, attachment, or expected output in the first message. ## Select the relevant area When possible, select the cells, range, table, or sheet you want Agent to focus on before you ask. This helps Agent avoid reviewing unrelated workbook content. For example: 1. Select a table in Excel. 2. Ask Agent: "Summarize this table and flag unusual values or missing fields." If you already know the cell reference, include it in the prompt. For example: "Use `Revenue!A1:H120`." ## Choose the right mode Agent modes control whether Agent can only review content or can also make changes. * Use **read-only mode** for summaries, explanations, searches, audits, and comparisons. * Use **Ask for edit mode** when Agent should change a workbook, but you want to approve the change first. * Use **Agent mode** only for trusted tasks where you have described the desired result clearly. See [Agent modes and approvals](/assistant/agent/agent-modes-and-approvals) for details. ## Attach files when needed Attach files when the information Agent needs is not already in the open workbook. Agent can use workbooks, CSV files, JSON files, documents, text files, and images as context for your request. Attached files stay on your device. Agent uses the relevant parts for your request rather than uploading the full file. See [Using files and attachments](/assistant/agent/using-files-and-attachments) for examples. ## Review Agent's work For important workbook changes, review the affected cells, formulas, or sheets after Agent finishes. You can also ask Agent to check its work: > Re-read the cells you changed and summarize the formulas, values, and formatting updates. For guidance on responsible AI use, see [AI Guidelines](/assistant/agent/ai-guidelines). # Chatting with Agent Agent uses a chat interface. You can send a message, attach files, ask follow-up questions, and guide a task step by step.

A good Agent conversation usually starts broad enough to explain the goal, then narrows into specific sheets, ranges, checks, or edits. You do not need special commands, but clear instructions produce better results. ## Write effective prompts Tell Agent what you want, where it should look, and how detailed the answer should be. Use this pattern: > Do \[task] using \[sheet, range, workbook, or attachment]. Return \[format or level of detail]. Examples: * "Analyze `Revenue!A1:H120` and summarize the key trends in bullets." * "Review the active sheet and identify formulas that look inconsistent." * "Create a pivot table from the selected range with Region as rows and Revenue as values." * "Compare the attached workbook against the open workbook and list material differences." When a task has risk, state the limits directly: > Review the model for issues, but do not change the workbook. > Preview the proposed edits before writing anything. ## Ask useful follow-up questions You can continue the same conversation with follow-up requests. Agent remembers earlier messages in that conversation, so you can refine the answer without restating everything. Examples: * "Show the same analysis by quarter." * "Explain the second issue in more detail." * "Which formulas drive the final output?" * "Apply that formatting to the rest of the table after I approve it." For longer work, ask Agent to proceed in stages. For example, ask for a summary first, then ask for the top risks, then ask for suggested fixes. ## Control the answer format If you need a specific format, ask for it. Agent can usually adapt its response to a short summary, a checklist, a table, or a step-by-step explanation. Examples: * "Return a table with columns for Sheet, Cell, Issue, Severity, and Recommendation." * "Give me a short executive summary first, then the detailed findings." * "List only the top five issues and include cell references." This is especially helpful when you need to share the result with a reviewer or compare multiple outputs. ## Retry or edit messages If Agent misunderstood your request, retry or edit your message with clearer instructions. For example, change: > Analyze this sheet. To: > Analyze the active sheet. Focus on formula consistency, hardcoded assumptions, and external links. Return a short list of issues with cell references. ## Use checklists for longer tasks For multi-step work, Agent may show a checklist so you can follow progress. This is useful for workbook review, data cleanup, workbook comparison, or multi-sheet analysis. If the checklist misses a step, tell Agent before it continues. If a step might change the workbook, ask Agent to preview the change or wait for approval. ## Manage long conversations If a conversation gets long, Agent may summarize earlier messages so it can keep working. If Agent misses an important detail later, restate it in your next message. Start a new conversation when you switch to a different workbook, topic, or review goal. This keeps the context cleaner and makes the conversation easier to find later. ## Tips * Select the relevant range before asking about specific cells. * Include sheet names and cell references when you know them. * Ask for a preview before large edits. * Ask Agent to explain assumptions before building new analysis. * Use Skills for repeated instructions or team-specific conventions. * Review important AI responses before relying on them. See [AI Guidelines](/assistant/agent/ai-guidelines). # Agent modes and approvals Agent modes control what Agent can do in your workbook. Use them to decide whether Agent should only review content, ask before edits, or work with fewer interruptions.

Choose the mode before you start a task. If you are unsure, start in read-only mode and switch only when you want Agent to edit the workbook. ## Read-only mode Use read-only mode when you want Agent to review, summarize, explain, search, or compare workbook content without changing anything. Good uses include: * Summarizing a workbook or sheet. * Explaining formulas and calculation flow. * Searching for values, links, named ranges, or references. * Reviewing a model for issues. * Comparing workbook versions. * Using an attachment as background for analysis. Read-only mode is the safest choice for audits, first-pass reviews, and exploratory questions. ## Ask for edit mode Use Ask for edit mode when you want Agent to make changes, but you want to approve them first. Agent may show an approval prompt before it edits workbook content or saved instructions. Good uses include: * Writing values or formulas. * Clearing or copying ranges. * Formatting cells. * Adding, renaming, or deleting sheets. * Creating or updating pivot tables. * Creating or editing Skills. This mode is a good default for workbook changes because it gives you a review point before content is modified. ## Agent mode Use Agent mode when you want Agent to work with fewer interruptions. This is best for trusted tasks where you have already described the result clearly and the workbook risk is low. Review the workbook after important changes, especially if the task affects formulas, model logic, hidden sheets, linked workbooks, or large ranges. ## Approval prompts When Agent needs permission, it may show an approval prompt with details about the action. Review the prompt before approving. You can usually choose to: * Approve the action. * Reject the action. * Skip the action. If the prompt is unclear, reject or skip it and ask Agent to explain what it planned to do. A clear approval prompt should make the affected workbook area and action understandable. ## Replacing existing content Agent is designed to avoid replacing existing workbook content by accident. If an edit would replace filled cells, Agent may stop and ask for confirmation. If you want Agent to replace existing content, say so clearly. For example: > Replace the existing summary table on `Summary!A1:F20` with the new version. If you do not want replacement, say that too: > Do not overwrite existing cells. If the target range is not empty, stop and ask me first. ## Best practices * Use read-only mode for review and exploration. * Use Ask for edit mode for workbook changes. * Approve only actions you understand. * Ask for a preview before large edits. * Save a copy of important workbooks before major changes. * Ask Agent to re-read changed ranges and summarize what changed. For AI usage and review guidance, see [AI Guidelines](/assistant/agent/ai-guidelines). # Using files and attachments Agent can use attached files as part of a conversation. Attachments are helpful when the information Agent needs is not already in the open workbook. Attached files stay on your device. Agent reads the parts needed for your request and sends only the relevant information needed for the AI response.

## Supported file types Agent can work with common workbook, data, document, text, and image files. Examples include Excel workbooks, CSV files, JSON files, PDFs, Word documents, text files, and screenshots. File support can vary by your organization's configuration and by the size or complexity of the file. If Agent cannot read a file, try a smaller export, a clearer screenshot, or a more focused prompt. ## When to attach files Use attachments when you want Agent to use information outside the open workbook. Common examples include: * Comparing two versions of a workbook. * Analyzing a source file that is not open in Excel. * Using a document as background information. * Reviewing data from a CSV or JSON file. * Explaining a screenshot or image. * Reconciling workbook content against another file. Attachments work best when you tell Agent exactly how each file should be used. For example, say whether an attached workbook is the prior version, the target version, or supporting evidence. ## How to refer to attachments If you attach more than one file, mention the file name in your request. You can also type `@` to select from available attachments. Examples: * "Compare `May forecast.xlsx` with the open workbook." * "Use the attached PDF as background and summarize the assumptions in this sheet." * "Read `transactions.csv` and tell me which columns look useful for a revenue analysis." * "Use `policy.docx` as the source of rules and check whether the workbook follows them." ## Keep requests focused Large files can contain more information than Agent needs for a single answer. If the first response is too broad, ask Agent to focus on a specific sheet, section, page, range, or column. For example: > In `transactions.csv`, focus only on customer, invoice date, amount, and status. Summarize overdue amounts by customer. ## Privacy and review Agent uses the relevant parts of attachments for your request rather than uploading the full file by default. Do not attach sensitive files unless your organization allows that use. For more detail, see [AI Guidelines](/assistant/agent/ai-guidelines). ## Tips * Tell Agent which file to use if you attach more than one. * Include the desired answer format in your request. * Reattach a file if Agent says it cannot find it. * Ask for a summary first when an attachment is large or unfamiliar. * Ask Agent to cite file names, pages, sheets, or columns when the source matters. # Conversations and history Agent saves conversations so you can return to previous work, continue a review, or reuse an earlier answer.

A conversation can include messages, workbook references, attached files, saved outputs, and instructions Agent used while working. Keeping related work in one conversation helps Agent understand follow-up questions. Starting a new conversation helps keep unrelated work separate. ## What a conversation contains A saved conversation may include: * Your messages and Agent's responses. * References to workbook context used during the task. * Attached files used in the conversation. * Saved outputs created by Agent. * Follow-up questions and decisions made during the workflow. Conversations are stored locally in browser storage on your device. See [Settings and storage](/assistant/agent/settings-and-storage) for storage details. ## Start a new conversation Start a new conversation when you change topics, switch workbooks, or begin a new workflow. This keeps Agent focused and makes the conversation easier to find later. Good first messages make good conversation titles. For example, "Review Q4 forecast workbook" is easier to recognize than "Help with this file." ## Continue existing work Reopen a conversation when you want to continue earlier analysis, review a prior answer, or ask follow-up questions about the same workbook. Useful follow-ups include: * "Continue from the last finding." * "Explain the second issue in more detail." * "Use the same review criteria on the next sheet." * "Create a summary of what we found so far." If Agent seems to miss an earlier detail in a long conversation, restate the detail in your next message. ## Search and organize Use clear first messages and specific workbook names so conversation history is easier to search. When a task becomes a different topic, start a new conversation instead of adding unrelated work to the old one. Before clearing local data, review old conversations and saved outputs you may need later. # Skills Skills are saved instructions that tell Agent how to handle repeated tasks, team conventions, or specialized workflows. Use Skills when you want Agent to apply the same guidance consistently across conversations.

A Skill can be as simple as a model review checklist or as specific as a monthly reporting process. The goal is to save instructions you would otherwise type again and again. ## When to use Skills Create a Skill when you often give Agent the same instructions. Skills work well for: * Team formatting standards. * Model review checklists. * Naming conventions for sheets, ranges, or tables. * Repeated workflows, such as monthly reporting or workbook cleanup. * Company-specific guidance that Agent should follow. * Preferred response formats, such as finding tables or executive summaries. If the instruction is only useful once, keep it in the chat. If it becomes a pattern, turn it into a Skill. ## Built-in and custom Skills Agent can show built-in Skills and user-created Skills. Built-in Skills are provided by Coherent Assistant. Custom Skills can be created, edited, or deleted from the Skills page. Custom Skills are useful for team-specific guidance. For example, a finance team might create a Skill that tells Agent how to review model assumptions, classify issue severity, and format findings. ## What to include in a Skill A useful Skill should include: * A clear name. * A short description. * Tags that make it easy to find. * Specific instructions Agent can follow. * Examples when the workflow has important details. * Any limits Agent should respect, such as "do not edit formulas unless asked." Write Skills as instructions, not as background essays. Agent should be able to read the Skill and know what to do. ## Example Skill outline A workbook review Skill might include: * Review formulas for inconsistencies, hardcoded values, external links, and errors. * Group findings by severity: High, Medium, or Low. * Include sheet names and cell references. * Suggest fixes, but do not change the workbook unless the user asks. * Return a short executive summary before the detailed findings. ## Using a Skill Use a Skill when you want Agent to apply the same guidance consistently. For example: > Use our model review Skill and review this workbook. If Agent applies the Skill too broadly, narrow the request with a sheet, range, or output format. # Saved outputs Agent may save files or results, also called artifacts, during a conversation so you can review them later. Saved outputs are useful when a result is too large for the chat, when Agent creates a reusable artifact, or when a comparison needs a structured record.

Session artifacts and saved outputs browser

## What Agent may save Saved outputs, or artifacts, can include: * Attached files used during the conversation. * Workbook details collected during analysis. * Tables created for review. * Long results that do not fit neatly in chat. * Workbook comparison results. * Images or screenshots used as context. Saved outputs are tied to the conversation where Agent created or used them. ## Viewing saved outputs Use the session artifacts or saved outputs browser to review results from the current Agent conversation. This is helpful when Agent creates a table, saves a long analysis, compares workbooks, or refers to a result that is easier to inspect outside the chat. If Agent mentions a saved output or artifact, open the browser and review it directly. For important work, compare the saved output against the source workbook or attachment before relying on it. ## When saved outputs are useful Saved outputs are most useful for tasks that produce reusable or detailed results, such as: * A workbook review with many findings. * A table summary created from a selected range or attached CSV. * A comparison between two workbook versions. * A long explanation that you want to keep outside the chat. * A generated checklist or review record. You can ask Agent to summarize a saved output later in the same conversation. ## Managing saved outputs Saved outputs use local browser storage on your device. If storage grows large, review saved outputs and old conversations before clearing data. Clearing local Agent data can remove saved outputs, conversations, messages, Skills, and temporary files. See [Settings and storage](/assistant/agent/settings-and-storage) before clearing data. ## Tip If Agent refers to a saved output, open it directly before taking action. The chat summary may not include every detail in the saved result. # Settings and storage Agent settings let you choose how Agent works and manage the data saved on your device.

Use settings when you need to adjust model options, conversation size, display preferences, or local storage. The exact options available can vary by organization. ## General settings General settings may include the model, conversation size, and cost display options available to your organization. If a setting is unavailable, your administrator may manage it centrally. Choose settings based on the task. Short reviews and simple edits usually need less context. Longer analysis, multi-step reviews, and conversations with attachments may need more context. ## Conversation size Conversation size controls how much prior chat and workbook information Agent can use at once. Larger sizes can support longer work sessions, but they may use more AI capacity or cost more depending on your organization's configuration. If Agent forgets an earlier detail, restate it in your next message. If the conversation has become crowded with unrelated work, start a new conversation. ## Local data and storage Agent stores conversations, messages, saved outputs or artifacts, Skills, and some temporary files in browser storage on your device. This lets you return to prior work and reuse saved outputs without uploading the full workbook or attached files. When Agent needs an AI response, it sends only the relevant information for that request. See [AI Guidelines](/assistant/agent/ai-guidelines) for more detail. ## Clearing local data Use the clear-all option only when you want to remove Agent data from the current device. This can remove local conversations, messages, saved outputs or artifacts, Skills, and temporary files. It cannot be undone. Before clearing data, check whether you need to keep any saved outputs, conversation history, or custom Skills. ## Tip If storage looks high, review saved outputs, artifacts, and old conversations before clearing all local data. # Workflows Agent workflows show common ways to use Agent for workbook review, edits, data summaries, pivot tables, audits, comparisons, and knowledge base research.

Agent organizes workbook tasks into workflow options — Start with the workflow closest to your goal, then narrow the task as Agent learns more about your workbook.

Use these pages as starting points. Adapt the prompts to your workbook, your organization's review standards, and the level of detail you need. ## Available workflows * [Analyze a workbook](/assistant/agent/workflows/analyze-a-workbook) * [Edit cells, ranges, and sheets](/assistant/agent/workflows/edit-cells-ranges-and-sheets) * [Work with tables and SQL](/assistant/agent/workflows/work-with-tables-and-sql) * [Create and manage pivot tables](/assistant/agent/workflows/create-and-manage-pivottables) * [Audit a workbook](/assistant/agent/workflows/audit-a-workbook) * [Compare workbooks](/assistant/agent/workflows/compare-workbooks) * [Use Agent with knowledge base articles](/assistant/agent/workflows/use-agent-with-knowledge-base-articles) ## How to use a workflow Start with the workflow closest to your goal. Run the first prompt as a review step, inspect Agent's response, then ask a narrower follow-up. For workbook edits, ask for a preview before Agent writes to the workbook. A good workflow prompt names: * The sheet, range, workbook, table, file, or article Agent should use. * Whether you want review only or workbook changes. * The level of detail you need. * The answer format, such as bullets, a table, or a new worksheet. ## Prompt tips * Select the relevant range before asking about specific cells. * Ask Agent to include cell references when findings matter. * Ask for a summary first when the workbook is large or unfamiliar. * Use read-only mode for exploration and Ask for edit mode for changes. * Break large requests into smaller steps when Agent needs to inspect many sheets or files. # Analyze a workbook Use this workflow when you need to understand a workbook before you edit it, audit it, or hand it off to someone else. Agent can map the workbook structure, explain formulas, identify key assumptions, and point you toward the next best step. {% hint style="info" %} **Best first prompt:** "Summarize this workbook. Identify the main sheets, key inputs, outputs, assumptions, and anything that needs closer review. Include sheet or cell references where helpful." {% endhint %} ## At a glance * **Best for:** Workbook orientation, model handoff, formula explanation, and early review. * **Output:** A workbook summary, key sheets, inputs, outputs, assumptions, review signals, and follow-up questions. * **Recommended mode:** Read-only mode. ## When to use this workflow Use this workflow when you need a fast read of a workbook, sheet, range, or model before deciding what to do next. Common goals include: * Understand the purpose of a workbook. * Find the main inputs, outputs, and assumptions. * Explain formulas and calculation flow. * Identify unusual values or structures. * Prepare for a cleanup, audit, or handover. ## Starter prompts by goal ### Understand the workbook structure * "Summarize this workbook and identify the main sheets." * "Analyze the active sheet and explain how it fits into the workbook." * "Create an executive summary of this workbook for a reviewer." ### Find inputs, outputs, and assumptions * "Find the main inputs, outputs, and assumptions in this model." * "List the key assumption cells and explain what each one appears to control." * "Return a table with Sheet, Cell or Range, Purpose, and Notes." ### Explain formulas and flow * "Which formulas drive the final output?" * "Explain the calculation flow from inputs to outputs." * "Review the selected range and explain what the formulas calculate." ### Check whether the workbook is ready for review * "Review the selected range and tell me whether it looks like a clean table." * "Show the most important issues first. Include sheet and cell references." * "List what you can confirm from the workbook, then list assumptions you are making." ## Recommended workflow 1. **Pick the scope.** Select the sheet or range you want Agent to review, or name the workbook area in your prompt. 2. **Ask for a summary first.** Start broad enough to understand the workbook, but ask Agent to include sheet or cell references when it finds something important. 3. **Review the evidence.** Check any cells, ranges, or sheets Agent points out before you rely on the answer. 4. **Drill into one area.** Ask a narrower follow-up about formulas, assumptions, outputs, or unusual structures. 5. **Choose the next workflow.** If you find risks, move to an audit workflow. If you need changes, move to an editing workflow and ask for a preview first. ## Good follow-up requests

Show follow-up prompts

* "Where are the hardcoded assumptions?" * "Which sheets look unused or supporting-only?" * "What should I review before changing this workbook?" * "Group the findings by Inputs, Calculations, Outputs, and Review notes." * "Turn this into a short handover note for another analyst."

## Tip Ask Agent to separate workbook evidence from interpretation when the workbook is unfamiliar. For example: "List what you can confirm from the workbook, then list assumptions you are making." ## Next best workflows Use these pages when analysis turns into review, editing, or version comparison. {% content-ref url="/pages/etefVmN87rI7HeGpM8kh" %} [Audit a workbook](/assistant/agent/workflows/audit-a-workbook) {% endcontent-ref %} {% content-ref url="/pages/GkuuR40uEzhgWq74cjRe" %} [Edit cells, ranges, and sheets](/assistant/agent/workflows/edit-cells-ranges-and-sheets) {% endcontent-ref %} {% content-ref url="/pages/eTbBJTerG3NPw9Jka3fd" %} [Compare workbooks](/assistant/agent/workflows/compare-workbooks) {% endcontent-ref %} # Edit cells, ranges, and sheets Agent can help update workbook content, formulas, formatting, sheets, and ranges. Use this workflow when you want Agent to change the workbook, not just explain it. For important files, use Ask for edit mode so you can approve changes before they are applied. ## When to use this workflow Use this workflow when you want Agent to make workbook changes such as: * Writing values or formulas. * Clearing ranges. * Copying values or formulas. * Formatting cells and ranges. * Adding, renaming, or deleting sheets. * Reusing workbook styles. If you only want a review, use read-only mode and say that Agent should not change the workbook. ## Example prompts * "Write these assumptions into `Assumptions!B5:B10`." * "Format the header row to match the table above." * "Add a new summary sheet for the selected data." * "Copy the formulas from row 12 down through row 24." * "Preview a cleanup plan for this sheet before making changes." ## Recommended steps 1. Tell Agent exactly what range or sheet to change. 2. If existing content should be replaced, say that clearly. 3. Ask for a preview when the change affects formulas, large ranges, or existing content. 4. Review the approval prompt before allowing the change. 5. Ask Agent to check the edited range after it finishes. ## Safer edit prompts * "Preview the changes before writing anything." * "Do not overwrite existing cells without asking me first." * "Use Ask for edit mode and wait for approval before changing the workbook." * "After editing, re-read the changed range and summarize what changed." ## Tip Be explicit about replacement. "Add below the existing table" and "replace `Summary!A1:F20`" lead to very different actions. # Work with tables and SQL Agent can help summarize table-style data. You can ask questions such as "group this by month" or "show the top 10 customers," and Agent can use SQL when that is the best way to answer. Use this workflow when your data is arranged in rows and columns and you need a structured summary, filter, join, or calculation. ## When to use this workflow Use this workflow when your data is arranged in rows and columns and you want to filter, group, join, or summarize it. Good examples include: * Summarizing transactions by month, region, or customer. * Finding duplicate records. * Combining data from two sheets or attachments. * Creating a summary table for later use. * Checking missing values or inconsistent categories. ## Example prompts * "Create a table from the selected range and summarize revenue by region." * "Find the top 10 customers by revenue." * "Join these two attached CSV files and return the matching rows." * "Use `Sales!A1:H500` and count rows by status." * "Check this table for duplicate invoice IDs and missing amounts." ## Recommended steps 1. Select the source range or name the sheet and range. 2. Ask Agent to check the headers and data types. 3. Ask for the summary, filter, join, or calculation you want. 4. Review the result and ask for a saved output if you need to reuse it. 5. If the result should be written to the workbook, ask for a preview first. ## Make table requests precise When possible, name the columns Agent should use. This reduces ambiguity when a table has similar fields. For example: > Use `Sales!A1:H500`. Group by `Region` and `Invoice Month`, sum `Revenue`, and return the top five regions by total revenue. ## Tip This works best when the source range has clear headers and consistent column types. # Create and manage PivotTables Agent can create, review, refresh, sort, filter, and adjust pivot tables. Use this workflow when you want an Excel summary that can be refreshed, filtered, and adjusted later. Pivot tables work best when the source range has clear headers and consistent column types. ## When to use this workflow Use this workflow when you want Agent to summarize structured data in Excel. Agent can help with: * Creating a pivot table from a source range. * Listing existing pivot tables. * Adding or removing fields. * Setting filters. * Sorting and refreshing pivot tables. * Adjusting the layout. ## Example prompts * "Create a pivot table from the selected range with Region as rows and Revenue as values." * "Refresh all pivot tables in this workbook." * "Filter this pivot table to show only FY2025." * "Add Product as a column field and sort revenue descending." * "Inspect this source table and recommend a pivot table layout." ## Recommended steps 1. Select the source range or identify the source sheet and range. 2. Ask Agent to check headers and data types if the source data is unfamiliar. 3. Tell Agent which fields should be rows, columns, values, and filters. 4. Confirm where the pivot table should be created. 5. Review the pivot table and ask Agent to adjust fields if needed. ## Safer pivot table prompts * "Preview the pivot table layout before creating it." * "Create the pivot table on a new sheet named `Revenue Pivot`." * "Do not overwrite existing sheets or ranges." * "After creating it, summarize which fields were used." ## Tip If you are unsure which fields to use, ask Agent to inspect the source data and recommend a pivot table layout first. # Audit a workbook Agent can review workbooks for common modeling issues and summarize findings with cell references. Use this workflow when you want a structured review rather than a general workbook summary. Agent can help you find signals that deserve human review, but you should confirm the business context before changing formulas. ## When to use this workflow Use this workflow when you want Agent to review a workbook for possible errors, risks, or model quality issues. Agent can help identify issues such as: * Hardcoded numbers in formulas. * Links to other workbooks. * Formulas that refer to hidden sheets. * Inconsistent formulas. * Cells that show errors. * Formulas that may slow down the workbook. * References to entire rows or columns. * Text, spacing, or validation issues. ## Example prompts * "Review this workbook for formula issues and hardcoded constants." * "List potential model risks on the active sheet." * "Find formulas that reference hidden sheets or external workbooks." * "Run a workbook review and group findings by severity." * "Audit `Inputs!A1:K80` and return findings with cell references." ## Recommended steps 1. Use read-only mode for the first review. 2. Ask Agent to review the workbook or a specific sheet. 3. Review the grouped findings and cell references. 4. Ask for details on the highest-priority items. 5. Decide which issues should be fixed and ask for a preview before edits. ## Suggested finding format For a clearer review record, ask Agent to return a table with: * Severity. * Sheet and cell reference. * Issue type. * Why it matters. * Suggested next step. ## Tip A finding is a signal to review, not always proof of an error. Confirm the business context before changing formulas. # Compare workbooks Agent can compare workbooks and summarize the differences between versions. Use this workflow when you need to understand what changed, whether the changes look expected, and which differences deserve closer review. ## When to use this workflow Use this workflow when you need to understand what changed between two workbook versions. Common use cases include: * Reviewing changes before publishing a workbook. * Comparing a prior version to a current version. * Checking whether formulas, values, or sheets changed. * Preparing a summary of material differences. * Investigating why two versions produce different outputs. ## Example prompts * "Compare the attached workbook with the open workbook." * "Show the material differences between these two versions." * "Compare formulas and values between these files." * "Create a concise change summary for the workbook comparison." * "Compare outputs first, then list formula changes that may explain them." ## Recommended steps 1. Open one workbook and attach the other, or attach both files. 2. Tell Agent which file is the baseline and which file is the new version. 3. Ask for the level of detail you need. 4. Review any saved comparison output Agent creates. 5. Ask follow-up questions about specific sheets, ranges, or changed outputs. ## Useful comparison options Ask Agent to focus the comparison when the workbooks are large. For example: * "Compare only formulas and named ranges." * "Compare the Summary and Output sheets first." * "Ignore formatting differences." * "Group changes by sheet and show only material differences." ## Tip For large workbooks, ask Agent to summarize material differences first, then drill into specific sheets or ranges. # Use Agent with knowledge base articles Agent can search and read knowledge base articles when your organization makes them available. Use this workflow when Agent should answer using approved internal guidance instead of general knowledge alone. This is helpful for team standards, process rules, workbook requirements, and review checklists. ## When to use this workflow Use this workflow when Agent should answer using your organization's guidance. Good uses include: * Applying internal modeling standards. * Finding process guidance. * Explaining workbook requirements. * Following team-specific review steps. * Checking whether a workbook follows documented rules. ## Example prompts * "Search the knowledge base for revenue recognition guidance." * "Use the relevant knowledge base article to explain this workbook." * "Find our team guidance for formatting model outputs." * "Use the knowledge base to check whether this workbook follows our standards." * "Summarize the relevant article first, then apply it to the active sheet." ## Recommended steps 1. Ask Agent to search for a specific topic. 2. Review the article or summary Agent returns. 3. Ask Agent to apply the guidance to your workbook or task. 4. Ask for article references when the source matters. 5. If changes are needed, ask for a preview before Agent edits the workbook. ## Better search terms Specific terms produce better results. Include the policy area, workbook type, process name, or expected output. For example, "revenue recognition model inputs" is more useful than "policy." ## Tip When the answer affects compliance, process, or customer-facing work, ask Agent to show which article it used and which workbook evidence supports the conclusion. # Troubleshooting Agent Use this page when Agent does not behave as expected. Most issues can be resolved by narrowing the request, continuing the conversation, changing mode, or checking whether Agent has the right workbook context. ## Agent stops before finishing the task Sometimes Agent may stop while it is still working. You may notice that the **Cancel** button is no longer visible, but the task did not fully finish. To continue, send a short message such as: * "Continue." * "Please continue." * "Keep going." * "Resume where you left off." Agent will use the conversation so far and continue from the last step it understands. ## Agent gives a broad or shallow answer If Agent's answer is too general, narrow the request. Name the sheet, range, file, issue type, and output format you want. For example, change: > Analyze this workbook. To: > Review `Forecast!A1:K120` for formula inconsistencies and hardcoded values. Return the top five findings with cell references. ## Agent cannot find the right file or range If Agent cannot find context, check that the workbook is open, the range is selected, or the file is attached. If you attached more than one file, refer to the file by name or select it with `@`. For workbook ranges, include the sheet and cell reference when possible. ## Agent asks for approval unexpectedly Agent may ask for approval before changing workbook content, saved instructions, or areas that already contain data. Review the approval prompt before continuing. If you only wanted review, switch to read-only mode or say: > Review only. Do not change the workbook. ## Agent does not continue correctly If Agent does not continue correctly, briefly restate what it was doing. For example: > Continue reviewing the workbook for formula issues and pick up from the last finding. For long conversations, summarize the goal again and tell Agent which prior result to use. ## Still need help? If the issue continues, contact [Support](/support/faq) with the task you attempted, what happened, and any error message you saw. # Mapping Inputs & Outputs First step of getting any Excel model compatible with Spark is mapping. For Excel models to work with Spark, the workbook must have inputs and outputs mapped. This is typically done by setting specific Named Ranges in the Excel file, which Spark can recognize. These mapped inputs and outputs will correspond to the parameters of the API request and the API response. Before the introduction of Mapper, creating inputs and outputs involved manually establishing named ranges in the traditional manner. Now, you can simply select your inputs/outputs and add them with a single click. Here's how: 1. Open **Mapper** application. 2. Click on **Start mapping**. 3. Navigate in Excel ranges that you want to identify as inputs and outputs. Select the first input you would like to add. 4. The input will appear on the taskpane as shown below. 5. Click on **Add selected (1)**

{% hint style="info" %} You can also hold down CTRL and select multiple cells/ranges, this will let you map multiple inputs or outputs at the same time. {% endhint %} ### How are my inputs/outputs saved? After identifying your inputs and outputs with Mapper, you'll notice that Named Items are created for the selected cells. By default, Mapper assigns names to the inputs/outputs based on the content of the cell to their left. If the cell to the left is empty, Mapper will use the cell's address as the name. You can also create inputs and outputs by manually mapping them through Excel Name Manager. Every named range that is prefixed by `Xinput` or `Xoutput` will automatically added to Mapper.

{% hint style="info" %} You can always rename your inputs/outputs by clicking on the name in the taskpane. Do not use period/dot character ( . ) in your input or output names; this character is specifically reserved for defining sub-services. {% endhint %} ### What are inputs and outputs? In Excel, inputs serve as the user's starting point. They involve entering data crucial for your model. The outcomes of your Excel model represent the findings you wish to present to the end user. These outcomes can manifest as a calculated cell, a table, a chart, or a pivot table.

An example of input and output for a simple model can be BMI. For the body mass indicator calculator, the inputs of the model are age, body weight, and height whereas the output will be the {% hint style="info" %} For more details about mapping inputs and outputs, please check out [How to: Map inputs and outputs](/build-spark-services/map-inputs-and-outputs) {% endhint %} # Tables as Inputs & Outputs You can create inputs and outputs that consist of multiple cells instead of just one. It is possible to use tables as inputs and outputs through Mapper. There are some restrictions and details that might be a little different than your usual table, but mainly it is as easy as selecting a range and adding it through the Mapper. 1. Navigate to the **Mapper** application. 2. Select a range that consists of multiple cells. Make sure that the top left cell of your selection is not empty. Otherwise, the mapper won't detect your selection. 3. Click on **Add Selected** to add your input/output. {% hint style="info" %} Table inputs and outputs automatically get the address of the range as their name, you can change this through the taskpane or the Name Manager. {% endhint %} ### What separates table input from table output The mapper automatically determines whether a range is input or output by checking the bottom-right cell of the selection. Note that, you can always move inputs and outputs up and down to change an input to an output, or vice versa.

{% hint style="info" %} For more details about mapping inputs and outputs, please check out [How to: Map inputs and outputs](/build-spark-services/map-inputs-and-outputs) {% endhint %} # Calculation Differences Mapper allows you to see the difference in outputs in-between subsequent calculations. You can track constant and percentage changes on your outputs when you make changes to your inputs. This might be useful to see how different outputs are affected by different input combinations. Once you make changes to an input, it will be highlighted on the taskpane.

Hovering on the highlighted value will show the previous value of the input.

Outputs that are affected by the change in the inputs will have their value highlighted as well.

Positive and negative changes are shown for the outputs that are affected.

Seeing the constant value change is not always the most interesting information. You can click on the numbers to turn them into percentage changes.

# Linking your file to Spark There are several advantages to linking your local files with Spark Services. Once linkeda, you can access various applications conveniently. You can link your file without opening the Spark web interface. Just choose the folder where your service is located, find your service, and connect. After linking your file, a small tag is created within it, which Coherent Assistant recognizes. This tag functions only when logged into the appropriate environment. If you log into a different environment or if there's unauthorized access to your file, the link remains invisible and inaccessible to unauthorized users. ### How to link a file 1. Locate **Services** application. 2. Once you open the application, the first screen you see will tell you whether your file is connected or not.

When the file has no link in the current environment, above screen is shown.

3. You can link your file to an existing service by clicking on **Select a service**. Or create a brand new service by clicking on Create a new service. 4. Select the service and version you want to link your file to.

1) Locate your service. 2) Click on Next to confirm your selection. 3) Select the version you want to link your file. 4) And finally click on Select to finalize your link.

5. Once you have successfully linked your file, you will see the details of the linked service.

Once a file is linked to a service, you can create new versions of that service by uploading the file. # Creating a new service Excel files that are marked with inputs and outputs can be uploaded to Spark cloud and turned into services within minutes. To create a new service with Coherent Assistant, just open the Excel file that you want to convert to code and start Coherent Assistant on the sidebar. In Coherent Assistant when you create a service, you automatically link that Excel file to that service. ### How to create a service 1. Locate **Services** application. 2. Once you open the application, the first screen you see will tell you whether your file is linked or not.

3. You can create a new service from the file by clicking on the **Create a new service** button.

Fill all the necessary fields and click on Upload.

4. Fill in all the necessary fields and click on **Upload** {% hint style="info" %} You need to save your Excel file, before clicking on **Upload** button. {% endhint %}

Wait until the Publish button is highlighted, the upload process might take longer for bigger files.

5. You are almost there, once the file is successfully converted, click on **Publish**. ## Create service fields Not all the fields for creating a service are mandatory, below is a list of these fields and what they are used for: **Folder:** Used mainly for the organization and structure of your services, you are not able to move services between folders once they are created. **Name:** Name of the service that is being created. **Version:** Semantic versioning is a widely adopted scheme that encodes a version by a three-part version number (Major.Minor.Patch). In this scheme, risk and functionality are the measures of significance. * **Major:** Use the major version when you make changes in previously existing inputs and outputs. Or make logic changes that would affect existing outputs. * **Minor:** When you add new inputs or outputs to the service or add new logic that relates to these outputs. * **Patch:** When you make changes that don't affect the results of outputs. **Version label:** A short text to relate to versions. **Tags:** Tags that are related to this service. You can only add tags that are created by your tenant administration, if you don't have any tags please contact your admin. # Updating a service Any spark service in your environment can be downloaded, edited, and uploaded as a new version for that service through Coherent Assistant To create a new version of a service with Coherent Assistant, open a linked file or link your existing Excel file to a service in Spark. ### How to create a new version 1. Locate **services** application 2. Once you open the application, the first screen you see will tell you whether your file is linked or not. If your file is not linked, you need to link your file to a service to be able to create a new version. [Linking your file to Spark](/assistant/services/linking-your-file-to-spark)

4. Click on the Plus button to start creating a new version of your service. Make sure that your file is saved before this process.

5. Select the version you want to have for the version. Optionally enter a version label or select tags. 6. Click on **Upload**.

8. Wait for the upload and conversion process and click on **Publish**. ## Update service fields Not all the fields for updating a service are mandatory, below is a list of these fields and what they are used for: **Version:** Semantic versioning is a widely adopted scheme that encodes a version by a three-part version number (Major.Minor.Patch). In this scheme, risk and functionality are the measures of significance. * **Major:** Use the major version when you make changes in previously existing inputs and outputs. Or make logic changes that would affect existing outputs. * **Minor:** When you add new inputs or outputs to the service or add new logic that relates to these outputs. * **Patch:** When you make changes that don't affect the results of outputs. **Version label:** A short text to relate to versions. **Tags:** Tags that are related to this service. You can only add tags that are created by your tenant administration, if you don't have any tags please contact your admin. # Page 1 # Creating a solver Spark solver to perform a What-If Analysis similar to Goal Seek at each API call. Spark solver to perform a *What-If Analysis* similar to [Goal Seek](https://support.microsoft.com/en-us/office/use-goal-seek-to-find-the-result-you-want-by-adjusting-an-input-value-320cb99e-f4a4-417f-b1c3-4f369d6e66c7) at each API call. This is useful to determine the needed value to achieve a target input. For example, Goal Seek could be used to determine how long it would take to pay off a certain loan amount. Users can build a simple solver that works similarly to Excel’s Goal seek function in order to perform a What-If Analysis. This solver is recognized by Spark and returns the forecasted value. * For example, to reach a specific goal for the amount of annual premium paid by changing the sum assured. This is an effective method to find out how much an individual can be assured for, with a premium constraint. * If a Spark Service has multiple solves, they will be executed in alphabetical order. ### How to create a solver block? 1. Navigate to the **Solver** application. 2. Click on **Create a solver**. 3. Select the **target cell** and the **changing cell.** Select the algorithm you wish to use, and the value you wish to target.

4. Select an empty area that is at least 2 cells wide, and 13 cells long. {% hint style="info" %} You can rename the solver by changing the **XSolve\_\[address]** before creating or changing it through the name manager. {% endhint %} 5. Once the indicator is green, click on the **Create** button to add the solver block to your selection. ### Solver Block Parameters

Key	Value
`Run if`	A `TRUE` or `FALSE` value indicating whether or not this solve should be executed.
`Target Cell`	A link to the formulated cell that needs to reach the `Target value`. This is generally recommended to be defined as a difference between the desired `Target value` of `0`.
`Target value`	The value of the `Target cell` to achieve. This is best set to `0`.
`By changing`	A link to the cell that has to change in order to for the `Target cell` to reach the `Target value`.
`Solve algorithm`	The available options are `SECANT`, `STOPSATZERO`, `SMARTSECANT`, `BRENT`.
`Max change`	Maximum acceptable value of `\|Solve result - Target value\|` within `Max iterations`, default `1`.
`Max Iterations`	Maximum iterations for the number of solve.
`Initial guess`	Provide an initial guess to help reach the `Target value` sooner.
`Solve Started`	`TRUE` or `FALSE` value. Spark will write this into the cell during execution. This enables downstream calculations to use this value.
`Solve target`	This is provided in order to help assess how close the solve was in reaching the target, given the solve can conclude within the `Max change`. Spark will write this into the cell during execution. This enables downstream calculations to use this value.
`Solve iteration`	Spark will write this into the cell during execution. This enables downstream calculations to use this value.
`Solve result`	This will contain either the successful solve value or `#N/A`. Spark will write this into the cell during execution. This enables downstream calculations to use this value.
`Solve successful`	`TRUE` or `FALSE` value. Spark will write this into the cell during execution. This enables downstream calculations to use this value.

# Executing solvers Solver blocks are meant to be executed as part of your API. You can just upload your Excel file, turn it into a service, and every time you execute it, it will be solving the solver block. But we can also test the result of the block directly in Excel. ### How to execute a single solver block 1. Navigate to the **solver** application. You should see a list of solver blocks you have created, if not you need to create one. [Creating a solver](/assistant/solver/creating-a-solver) 2. Select the solver block you want to execute, click on the "..." (three dots) on the right side, and select **Details**. 3. Click on the **Execute** button.

Result of the execution is shown after it is complete.

You can copy the execution to clipboard and paste the table to Excel. # What is Shell? ## Spark Shell Overview Spark Shell is the fastest way to convert a workbook into a controlled application, with no development required. Shell allows workbook creators/owners to convert an existing Excel model into an Excel-based frontend for a Spark service, enabling users to instantly deploy standardized and version controlled versions of their workbook to users. Workbook owners can obfuscate logic to protect model IP if distributing to external users, without losing functionality from the model, and workbook operators will always be operating on the right version. Shell even manages moving workbook operators to new versions of your model when updated. With Shell, you can maintain the familiar Excel interface of your model, while getting the control and auditability benefits of Spark, managed by the business.

# 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)), 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.

## 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) 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.

### Mapper Integration Shell Creator contains an integration with [Mapper](/assistant/mapper/mapping-inputs-and-outputs) 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.

#### 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

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)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.

# Operating a Shell ## Shell File After [Creating a Shell](/assistant/shell/creating-a-shell), you will have a Shell file available to distribute to Operators who will use the Shell file. Shell files look and feel like the source workbook, and can be distributed through any method you would normally distribute Excel files - such as emails or through a webpage.

Example of Shell file Operator interface.

### Using a Shell File To use the Shell file, the Shell operator must have the Coherent Assistant Add-in installed. If a user does not have the Add-in installed and opens a Shell file, they will see a prompt to download it. When an operator uses a Shell file, it will look like a standard file, but calculations instead will be running through Spark's Xcall functionality (see for more information). When a user changes inputs in their Shell, a request will be sent to the Spark service powering the Shell, and the response will be delivered to the workbook. Note that an internet connection is required to use Shell.

All formulas replaced with an Xcall to the Spark Service.

If you choose to lock your Shell file, cells with formulas and static, non-input data will not be editable - inputs and blank cells can still be edited.

### Submit Button Shell files will call the API and produce an output whenever inputs are changed, but creators can include a Submit button in their Shell file to denote a flagged calculation from users, if required for their process (e.g., the Submit button may be used to track the final quote given for a rating workbook, or the final loan terms for an underwriting workbook). If your Shell file includes a Submit button, when an operator clicks it, the submission will be flagged with a separate call purpose in the API Call History page, and an event will be written to the business event log on Spark. Additionally, creators can configure the Submit button to send data to an external URL to send this data to internal systems or other applications. ### Authentication Shells can be configured to require the user to login to use the Shell. If this option is not selected during creation/update, the Shell will be usable by the Operator without login being required - the user will simply need the Coherent Assistant Add-in to use the Shell. If login is required for your Shell, a user will need Spark credentials within your tenant to use the Shell. If a user is not logged in and opens the Shell, they will see a prompt to login.

## Updated and Deactivated Shells Users will be notified when the Shell file has been updated or deactivated by a Shell creator. In the case of updates, Shell will automatically present a link to download the new version of the Shell file. Once a Shell file is updated or deactivated, the submit button in previous versions of Shell files (if they contain submit buttons) will be disabled. See [Managing Shell files](/assistant/shell/managing-shell-files) for more details on updating and deactivating Shell files.

Prompt to update Shell to the newest version

# Managing Shell files ## Shell Overview Existing Shell files will maintain an overview of the Shell, available by opening the source file for the Shell and logging into the Coherent Assistant Add-in. This page contains a summary of your Shell configuration, and management options of your Shell, including: * Updating your Shell * Deactivating your Shell * Downloading a copy of the latest version of your Shell * View API Call History for the service associated with your Shell As a Shell Creator, to manage a Shell you need to be linked to the source Spark service. From the Coherent Assistant Overview screen, choose *Services* and select the source Spark service that was uploaded when creating the shell. The menu will be available with the different management options.

### Version History You can also navigate to the Version History of your Shell from this page, which provides details and download options for each version of your Shell.

## Updating a Shell If you wish to update your model or the configurations of your Shell file, you can Update your Shell to seamlessly deploy an updated version of your Shell to users. You can access the Update Shell flow via the Overview page in your source file. The Update Shell flow is similar to the initial Shell creation flow, but it will maintain your existing configurations by default - you can edit configurations as needed. Note that updating your Shell file will upload a new version of your Shell service to Spark. Updating a Shell file will create and open a new Shell file on the desktop in the same process as initial Shell creation - refer to [Creating a Shell](/assistant/shell/creating-a-shell#create-shell) for more information. Shell users will be notified via Coherent Assistant when you update the Shell, and will be provided a download link for the new Shell. If your Shell contains a submit button, the Submit button on old Shell versions will be disabled, and will only work in the most recent Shell version.

## Deactivating a Shell Creators can deactivate a Shell if they no longer want any users to have access to use features of the Shell. You can deactivate via the dropdown menu shown above in the Overview page of your Shell source file. Deactivating a Shell will deactivate all versions of the Shell for all users.

You can deactivate a Shell immediately, or schedule deactivation for later. If you choose to deactivate later, you can select a specific date and time for deactivation.

Setting a specific deactivation date/time

Users can set a custom deactivation message to display to Shell operators once the Shell is deactivated, or use the default message:

If you choose to deactivate your Shell at a later date/time, you can cancel this pending deactivation via the Overview page in your Source file.

Deactivated Shell source files will show an inactive status in the Add-in. ![](/files/3piM3uICl77p0at4lSQR) ### Reactivating a Shell Deactivated Shells can be reactivated via the Shell Overview in the Shell source file. Reactivation is effective immediately for Shell files.

# Import Inputs ## Overview The Import Inputs function allows users to import data from a previous version of the shell, or from a mapped file with a similar input structure. ## Setting Up Imports In order to allow import inputs, the Shell file needs to be set up as part of the Shell setup process. An additional option has been added to the setup for Shell files below:

The options available to be selected are as follows: * Clear single cell inputs - Which will clear any single input fields in the target file prior to import * Clear array inputs - Which will clear any array input areas in the target file prior to import * Highlight empty cells - Which will highlight with a red border any empty cells that were not filled as part of the import, for example where a new field has been implemented in the target file that does not exist in the source * Allow partial array match - Which will allow for array inputs to be imported where available, for example where there has been a new column or row introduced in the target file that does not exist in the source file Once the Shell file has been updated, the import inputs button will be available to users to import relevant inputs. ## Using the Import Inputs Function When using the target Shell file, users can select the Import Inputs button in the top-right of the Coherent Assistant screen and select a file to import into the Target.

After selecting a file to import, a confirmation screen will appear and display warnings related to the configuration of the import inputs function. When a user proceeds with the import, the relevant input fields that are mapped will be imported. {% hint style="danger" %} Note: Where inputs have been removed in single cells or arrays, the import will not successfully complete. An enhancement to this functionality is currently being developed to allow for imports from the source where the field is not available in the target file. {% endhint %} This import functionality currently allows the following: * Inputs imported where there is an exact match between xInputs in the source and target * Inputs imported where there are new fields in the target that do not exist in the source * Inputs imported where there are changes in the position of the fields in the target compared to the source # Advanced Shell Configurations More advanced Shell configurations coming soon! # Common Problems # Uninstall Coherent Assistant # SPARK\_INFO {% hint style="info" %} This function is only available in Coherent Assistant and not implemented into [Neuron](/build-spark-services/neuron). Spark services created with this UDF will not include this functionality. {% endhint %} Returns information about the Coherent Assistant connection to Spark. This uses a similar pattern as the [`CELL()`](https://support.microsoft.com/en-us/excel/functions/cell-function) and [`INFO()`](https://support.microsoft.com/en-us/excel/functions/info-function) function. ## Syntax `CS.SPARK_INFO(type_text)`

type_text	Information	Example
`CHANNEL`	Environment channel	production
`VERSION`	Coherent Assistant environment channel	1.22.3
`AUTHENTICATED`	Login status	TRUE
`LOGINURL`	Login URL	https://spark.myenvironment.coherent.global/
`ENVIRONMENT`	Coherent environment	myenvironment
`TENANT`	Tenant name	mytenant
`SERVICE`	Spark service URI if linked	myfolder/myservice

# SPARK\_XCALL You can get more detailed information about how `SPARK_XCALL` works from [Using CS.SPARK\_XCALL() UDF](/build-spark-services/call-spark-service-apis/using-cs.spark_xcall-udf). # REGEXMATCH {% hint style="info" %} This function is only available in Coherent Assistant and not implemented into [Neuron](/build-spark-services/neuron). Spark services created with this UDF will not include this functionality. {% endhint %} Regular expression enabled [`MATCH()`](https://support.microsoft.com/en-us/excel/functions/match-function) function to search for a specified item in a range of cells, and then return the relative position of that item in the range. ## Syntax `CS.SPARK_REGEXMATCH(find_regex, within_text, [start_num])` | Parameter | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | `find_regex` \* | Regular expression pattern you want to match the `within_text` argument. It should be a valid regular expression string. | | `within_text` \* | Text string in which you want to search for a regular expression pattern. It should be a valid text or cell reference. | | `start_num` | If specified, this argument allows you to specify the starting position of the text. | ## Example Copy and paste the text below into cell A1 in a new worksheet. {% code overflow="wrap" %} ``` Hello, my name is John Doe. My email is john.doe@example.com. I live in New York, and I work as a software engineer. My hobbies include reading, hiking, and photography. Contact me at +1234567890. ``` {% endcode %} Copy and paste the regular expression below to the cell A2. ```regex [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,} ``` | Formula | Result | | ----------------------------- | ---------------------- | | `=CS.SPARK_REGEXMATCH(A2,A1)` | | # REGEXSEARCH {% hint style="info" %} This function is only available in Coherent Assistant and not implemented into [Neuron](/build-spark-services/neuron). Spark services created with this UDF will not include this functionality. {% endhint %} Regular expression enabled [`SEARCH()`](https://support.microsoft.com/en-us/excel/functions/match-function) function to locate one text string within a second text string. ## Syntax `CS.SPARK_REGEXSEARCH(find_regex, within_text, [start_num])` | Parameter | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | `find_regex` \* | Regular expression pattern you want to match the `within_text` argument. It should be a valid regular expression string. | | `within_text` \* | Text string in which you want to search for a regular expression pattern. It should be a valid text or cell reference. | | `start_num` | If specified, this argument allows you to specify the starting position of the text. | ## Example Copy and paste the text below into cell A1 in a new worksheet. {% code overflow="wrap" %} ``` Hello, my name is John Doe. My email is john.doe@example.com. I live in New York, and I work as a software engineer. My hobbies include reading, hiking, and photography. Contact me at +1234567890. ``` {% endcode %} Copy and paste the regular expression below to the cell A2. ```regex [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,} ``` | Formula | Result | | ------------------------------ | ------ | | `=CS.SPARK_REGEXSEARCH(A2,A1)` | 41 | # REGEXTEST {% hint style="info" %} This function is only available in Coherent Assistant and not implemented into [Neuron](/build-spark-services/neuron). Spark services created with this UDF will not include this functionality. {% endhint %} Regular expression enabled function that indicates a pattern exists within a text string. ## Syntax | Parameter | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | `find_regex` \* | Regular expression pattern you want to match the `within_text` argument. It should be a valid regular expression string. | | `within_text` \* | Text string in which you want to search for a regular expression pattern. It should be a valid text or cell reference. | | `start_num` | If specified, this argument allows you to specify the starting position of the text. | ## Example Copy and paste the text below into cell A1 in a new worksheet. {% code overflow="wrap" %} ``` Hello, my name is John Doe. My email is john.doe@example.com. I live in New York, and I work as a software engineer. My hobbies include reading, hiking, and photography. Contact me at +1234567890. ``` {% endcode %} Copy and paste the regular expression below to the cell A2. ```regex [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,} ``` | Formula | Result | | ---------------------------- | ------ | | `=CS.SPARK_REGEXTEST(A2,A1)` | TRUE | # Xcall legacy functions Xcall is designed for users to call other Spark service APIs inside one service. These custom functions are used to invoke the past iterations of `Xcall`. * [CALLAPI](/assistant/custom-functions/xcall-legacy-functions/callapi) and [GETOUTPUT](/assistant/custom-functions/xcall-legacy-functions/getoutput) * [UDFCALLAPI](/assistant/custom-functions/xcall-legacy-functions/udfcallapi) These functions are helper functions that were used to facilitate processing of API calls: * [FILTERJSON](/assistant/custom-functions/xcall-legacy-functions/filterjson) * [JSONTOXML](/assistant/custom-functions/xcall-legacy-functions/jsontoxml) and [XMLTOJSON](/assistant/custom-functions/xcall-legacy-functions/xmltojson) * [SETINPUT](/assistant/custom-functions/xcall-legacy-functions/setinput) # CALLAPI This legacy function allows the user to call Spark service API through Coherent Assistant. {% hint style="warning" %} This is an outdated custom function which we have replaced with [SPARK\_XCALL](/assistant/custom-functions/spark_xcall). This is available through the add-in for backward compatibility. {% endhint %} ## Syntax `CS.SPARK_CALLAPI(xcall_block)` * `xcall_block` Required. Range address of the XCall block in upstream service. E.g. `$A$1:$B$4`. You can also use a named range for convenience. ### UDFCall Block Create an UDFCall block in the Excel workbook (upstream service) to make an API call. The UDFCall block can be anywhere in your workbook but must be on the same sheet as your `Spark_UdfCallAPI` function. * This table needs to include * `CALLTYPE`: `SparkService` * `FOLDERNAME`: name of the folder containing downstream service. * `SERVICENAME`: name of downstream service. * `REQUESTBODY`: payload for calling downstream service. Must be in JSON format. You can copy the `REQUESTBODY` from downstream service API tester. If this is your first time using the SparkService we encourage to leave content of "request\_meta" empty. Spark will use the latest version and the default Service Type to execute this service. * XCall block example

* `REQUESTBODY` example (v3 format) ```json { "request_data": { "inputs": { "InputField": "InputValue" } }, "request_meta": {} } ``` ## Output The function will return a JSON formatted string with two parts. * The first, `metadata`, contains information about the call to the downstream service such as `status`, `error_code`, and `response_time`. * The second, `data`, contains the response body of the downstream service. **Response from Spark (example):** ```json { "metadata": { "name": null, "calltype": "SparkService", "status": "200", "error_code": "", "response_time": "225" }, "data": { "status": "Success", "response_data": { "outputs": { "OutputField": "OutputValue" }, "warnings": [], "errors": [], "service_chain": [] }, "response_meta": { "service_id": "166f5109-b01f-4d14-b10d-49669e3489e0", "version_id": "52e710a8-9ca1-4ab2-9366-dc304a9eb670", "version": "1.0.0", "process_time": 4, "call_id": "07ea654c-4136-4075-a195-7eaba15391c4", "compiler_type": "Type3", "compiler_version": "1.0.0", "source_hash": null, "engine_id": "F0D5B2B02645AAE15F63BABFBF94FBEF", "correlation_id": "", "system": "SPARK", "request_timestamp": "2022-02-28T16:14:25.148Z" }, "error": null } } ``` # FILTERJSON To make it easier to extract data from the Xcall response JSON, you can use the user-defined function Spark\_FilterJSON. This function also works for parsing any other JSON string. ## Syntax `CS.SPARK_FILTERJSON(json, path)` * `json` Required. Complete JSON string * `path` Required. The argument used to get the target data from \[JSON]. [JSONPath](https://jsonpath.com/) uses a standardized syntax. ## Example Copy the example JSON data below and paste it into the cell **A1** of a new worksheet. ```json { "name": "Chris", "age": 23, "address": { "city": "New York", "country": "America" }, "friends": [ { "name": "Emily", "hobbies": [ "biking", "music", "gaming" ] }, { "name": "John", "hobbies": [ "soccer", "gaming" ] } ] } ``` Below are some examples usage of FILTERJSON:

Formula	Result
`=CS.SPARK_FILTERJSON(A1,"name")`	`Chris`
`=CS.SPARK_FILTERJSON(A1,"friends[0].name")`	`Emily`
`=CS.SPARK_FILTERJSON(A1,"friends[0].hobbies[2]")`	`gaming`

## JSONPath Syntax Guide ### Hardcoded Direct Filtering You can write the path directly into the formula:

Formula	Result
`=CS.SPARK_FILTERJSON(A1,"age")`	`23`

You can also use multiple strings and match them to each other:

Formula	Result
`=CS.SPARK_FILTERJSON(A1,"friends"&"[0]&"name")`	`John`

### Column Filtering Return key values of each object inside an array. Copy and paste the formula below to any cell. ```excel-formula =CS.SPARK_FILTERJSON(A1,"friends[*].name") ``` This will result in a dynamic array representing all names inside the "`friends`" list.


`Emily`
`John`

### Dynamic Filtering JSON String: `{"outputs": {"number_value": 1, "text_value": "text"}}`

Formula Result

Formula	Result
`A2` `=CS.SPARK_FILTERJSON(JSON_String,"outputs."&CHAR(34)&A1&CHAR(34))`	`1`
`B2` `=CS.SPARK_FILTERJSON(JSON_String,"outputs."&CHAR(34)&B1&CHAR(34))`	`text`

A2

=CS.SPARK_FILTERJSON(JSON_String,"outputs."&CHAR(34)&A1&CHAR(34))

1

B2

=CS.SPARK_FILTERJSON(JSON_String,"outputs."&CHAR(34)&B1&CHAR(34))

text

{% hint style="danger" %} Please note that if you use a cell reference within the JSON path, the cell reference must be wrapped in `CHAR(34)`. Cell references can be utilized in any of the following filtering methods as well. {% endhint %} ### Subservice Filtering JSON String: `{"outputs": {"number.value": 1}}`

Formula	Result
`=CS.SPARK_FILTERJSON(JSON_String,"outputs."&"'number.value'")`	1

This method can be used for any case where a parameter's key in the JSON string contains a period `.`. To prevent the period from interfering with the JSON path syntax, the parameter's key must be wrapped in single quotation marks. ### Table Filtering (Dynamic Range) JSON String: `{"outputs": {"table": [{"key": "Key1", "value": 1}, {"key": "Key2", "value": 2}]}}`

Formula	Result
`=CS.SPARK_FILTERJSON(JSON_String,"outputs.table")`

If you define the JSON path down to an array, then `CS.SPARK_FILTERJSON` will return a dynamic range WITH the headers included. This means that the number of rows will automatically adjust to the number of data entries found within the JSON string. ### Column Filtering (Dynamic Range) JSON String: `{"outputs": {"table": [{"key": "Key1", "value": 1}, {"key": "Key2", "value": 2}]}}`

Formula	Result
=`CS.SPARK_FILTERJSON(JSON_String,"outputs.table[*].key")`

Please be aware that if you define the JSON path down to a column within a table array, then `CS.SPARK_FILTERJSON` will return a dynamic range WITHOUT the header included. It is recommended to hardcode the header row in this scenario and use cell references to the headers within the JSON path in the `CS.SPARK_FILTERJSON` formula. ### Row filtering JSON String: `{"outputs": {"table": [{"key": "Key1", "value": 1}, {"key": "Key2", "value": 2}]}}`

Formula	Result
`=CS.SPARK_FILTERJSON(JSON_String,"outputs.table[0]")`	`{"key":"Key1","value":1}`
`=CS.SPARK_FILTERJSON(JSON_String,"outputs.table[1]")`	`{"key":"Key2","value":2}`

Please note that the arrays are indexed starting at 0. To parse the first row of data, you would define `[0]` in the JSON path. To parse the third row of data, you would define `[2]` in the JSON path. ### Column & row filtering JSON String: `{"outputs": {"table": [{"key": "Key1", "value": 1}, {"key": "Key2", "value": 2}]}}`

Formula	Filtered output
`=CS.SPARK_FILTERJSON(JSON_String,"outputs.table[0].key")`	`Key1`
`=CS.SPARK_FILTERJSON(JSON_String,"outputs.table[1].key")`	`Key2`

## Sample file {% file src="/files/ghpUaEyS7qttfGdmaKL0" %} # GETOUTPUT Get specific output from CALLAPI block. {% hint style="warning" %} This is an outdated custom function which we have replaced with [SPARK\_XCALL](/assistant/custom-functions/spark_xcall). This is available through the add-in for backward compatibility. {% endhint %} ## Syntax `CS.SPARK_GETOUTPUT(xcall_block, output_name)` * `xcall_block`. Required. Range address of the XCall block in upstream service. E.g. `$A$1:$B$4`. You can also use a named range for convenience. * `output_name`. Required. Name of the requested output. ### UDFCall Block Create a [UDFCALLAPI](/assistant/custom-functions/xcall-legacy-functions/udfcallapi) block in the Excel workbook (upstream service) to make an API call. The UDFCall block can be anywhere in your workbook but must be on the same sheet as your `Spark_UdfCallAPI` function. * This table needs to include * `CALLTYPE`: `SparkService` * `FOLDERNAME`: name of the folder containing downstream service. * `SERVICENAME`: name of downstream service. * `REQUESTBODY`: payload for calling downstream service. Must be in JSON format. You can copy the `REQUESTBODY` from downstream service API tester. If this is your first time using the SparkService we encourage to leave content of "request\_meta" empty. Spark will use the latest version and the default Service Type to execute this service. * XCall block example

* `REQUESTBODY` example (v3 format) ```json { "request_data": { "inputs": { "InputField": "InputValue" } }, "request_meta": {} } ``` ## Output The function will return the value of the output that is selected. # JSONTOXML Converts an valid JSON string into XML and returns it as string. ## Syntax `CS.SPARK_JSONTOXML(cellAddressOrValue)` * `cellAddressOrValue` Required. Either the address of the cell that contains JSON or JSON string. ## Example Copy the example JSON data below and paste it into the cell **A1** of a new worksheet.

{
    "note": {
        "to": "Tove",
        "from": "Jani",
        "heading": "Reminder",
        "body": "Don't forget me this weekend!"
    }
}

Paste the custom function below and paste it into A2: ```excel-formula =CS.SPARK_JSONTOXML(A1) ``` You should get the following result: ```xml Tove Jani Reminder Don't forget me this weekend! ``` ## Sample file {% file src="/files/Jrzt7oCDSGuF0OEtSNsO" %} # SETINPUT Returns the absolute address of entered range or named item. ## Syntax `CS.SPARK_SETINPUT(input_location)` * `input_location`**:** Required. Address of the range that will be used to return the absolute address. You can also use named items for convenience. ## Example Given that the below formulas are pointing to ranges that are located in the worksheet called **`Sheet1`** | Formula | Result | | --------------------------- | ------------------ | | `=CS.SPARK_SETINPUT(A1)` | `Sheet1!$A$1` | | `=CS.SPARK_SETINPUT(A1:B9)` | `Sheet1!$A$1:$B$9` | Assume that we have a named item age that points to G3: | | | | ------------------------- | ------------- | | `=CS.SPARK_SETINPUT(age)` | `Sheet1!$G$3` | {% hint style="danger" %} If you update the name of the sheet where the named item or selected range is located in, the formula won't update automatically. You will need to refresh it manually. {% endhint %} # UDFCALLAPI This legacy function allows the user to call Spark service API through Coherent Assistant. {% hint style="warning" %} This is an outdated custom function which we have replaced with [SPARK\_XCALL](/assistant/custom-functions/spark_xcall). This is available through the add-in for backward compatibility. {% endhint %} ## Syntax `CS.SPARK_UDFCALLAPI([UDFCallTableRange])` * **XCallTableRange**: Required. Range address of the XCall block in upstream service. E.g. $A$1:$B$4. You can also use a named range for convenience. ### UDFCall Block Create an UDFCall block in the Excel workbook (upstream service) to make an API call. The UDFCall block can be anywhere in your workbook but must be on the same sheet as your `Spark_UdfCallAPI` function. * This table needs to include * `CALLTYPE`: `SparkService` * `FOLDERNAME`: name of the folder containing downstream service. * `SERVICENAME`: name of downstream service. * `REQUESTBODY`: payload for calling downstream service. Must be in JSON format. You can copy the `REQUESTBODY` from downstream service API tester. If this is your first time using the SparkService we encourage to leave content of "request\_meta" empty. Spark will use the latest version and the default Service Type to execute this service. * XCall block example

* `REQUESTBODY` example (v3 format) ```json { "request_data": { "inputs": { "InputField": "InputValue" } }, "request_meta": {} } ``` ## Output The function will return a JSON formatted string with two parts. * The first, `metadata`, contains information about the call to the downstream service such as `status`, `error_code`, and `response_time`. * The second, `data`, contains the response body of the downstream service. **Response from Spark (example):** ```json { "metadata": { "name": null, "calltype": "SparkService", "status": "200", "error_code": "", "response_time": "225" }, "data": { "status": "Success", "response_data": { "outputs": { "OutputField": "OutputValue" }, "warnings": [], "errors": [], "service_chain": [] }, "response_meta": { "service_id": "166f5109-b01f-4d14-b10d-49669e3489e0", "version_id": "52e710a8-9ca1-4ab2-9366-dc304a9eb670", "version": "1.0.0", "process_time": 4, "call_id": "07ea654c-4136-4075-a195-7eaba15391c4", "compiler_type": "Type3", "compiler_version": "1.0.0", "source_hash": null, "engine_id": "F0D5B2B02645AAE15F63BABFBF94FBEF", "correlation_id": "", "system": "SPARK", "request_timestamp": "2022-02-28T16:14:25.148Z" }, "error": null } } ``` # XMLTOJSON Converts an valid XML string into JSON and returns it as string. ## Syntax `CS.SPARK_XMLTOJSON(cellAddressOrValue)` * `cellAddressOrValue` Required. Either the address of the cell that contains XML or XML string. ## Example Copy the example XML data below and paste it into the cell **A1** of a new worksheet. ```xml Tove Jani Reminder Don't forget me this weekend! ``` Paste the custom function below and paste it into A2: ```excel-formula =CS.SPARK_XMLTOJSON(A1) ``` You should get the following result: ```json { "note": { "to": "Tove", "from": "Jani", "heading": "Reminder", "body": "Don't forget me this weekend!" } } ``` # CA to Hybrid Runner Coherent Assistant can integrate with a deployed hybrid runner, allowing the logical engine to process data locally within the hybrid runner. With a few configuration steps, the results are seamlessly returned to the Coherent Assistant. This setup is ideal for customers with strict data processing regulations, enabling them to utilize Spark within their secure environment without having to transfer data externally. Below is a diagram to illustrate the process of Coherent Assistant interacting with a locally deployed Hybrid Runner.

We are assuming that the Hybrid Runner has been properly set up locally in your environment. If not, please visit \ \ **Steps for setting up Coherent Assistant to Hybrid Runner** 1. Coherent Assistant should be properly installed in your environment, if not please visit 2. Log on to your SaaS tenant and go to Options\ ![](/files/kWzjUEQCnaycDXqMNgYe) 3. Under **General configurations**, you will need to make adjustments to the Coherent Assistant Hybrid Runner URL. This will be the location of where your Hybrid Runner is set up. Hit Save to save the configuration

4. Open your Excel file containing Coherent Assistant, log in to your tenant, and now your Assistant will be able to connect to your Hybrid Runner. Coherent Assistant will now redirect traffic to your locally deployed runner. The behavior of Coherent Assistant remains consistent across both the SaaS platform and the Hybrid Runner. However, the key difference lies in the location of data processing. Since the processing occurs locally within the Hybrid Runner, the SaaS platform will not retain a record of the API history. It is the customer's responsibility to manage the saving and storage of API history post-processing. # Welcome to Coherent Control Welcome to Coherent Control, a simple lightweight governance tool for managing spreadsheets. Control gives you the ability to manage master templates of files, lock down specific content and manage approval cycles for critical assets. ### Get Started

			Cover image
Quickstart	Set up a Control Process	/pages/7FvWQMF0kTK7HGhlQfmo	/files/L1j9UKyIAxooRVjc5qFE	/pages/7FvWQMF0kTK7HGhlQfmo
Platform Overview	Get more detail about the platform and use cases	/pages/pple4rdJklHaOCGtwzRN	/files/uiLPOKFexGlwcRXSIT3k
Processes	Learn about the different types of processes	/pages/LlTN9gPwcM5m33LFHvpc	/files/SLc3fVKcC8Wu5FmIlcFK	https://github.com/GitbookIO/gitbook-templates/blob/main/product-docs/broken-reference/README.md
Workflow Templates	Learn how templates work and how they can be set up	/pages/nivgs4mpqkQ9GRuUNeFj	/files/LeTTX3otUGiy4EjI5G6c	/pages/QPzbTvC6XsT5gERiU43E
User Management	Learn how users and roles are managed across Control	/pages/HvIPUl0gguR3dDYhXY1x	/files/j310mdRiKwGMt3XDKabh
Coherent Assistant	Learn more about the Coherent Assistant Add-In	/spaces/QQAtOKkd2V4rbmsT77rn/pages/de2ZcHBecL8dyX0AKFss	/files/DOf6Z6EUQnjzBVhVVLQd

# Welcome Welcome to Coherent Control, please find below some quick reference material to help you familiarize yourself with the product and get a better view on how to set up and work with processes. ### Getting Started Video {% embed url="" %} ### Create a process

There are two straightforward ways to create a process, either via the Platform (web) UI, or through the[ Coherent Assistant.](/assistant) Both ways are quick and easy to get started! ### Task Submission If you have been sent a workbook which uses Coherent Control and you are required to submit tasks, this can be done through the Coherent Assistant. Take a look at the [Task Submission](/control/processes/task-submission) documentation to get started # Introduction Coherent Control gives teams a controlled way to manage spreadsheet-driven work. It combines workflow, permissions, and file governance in one platform. Teams use it to standardize spreadsheets, control edits, and track approvals across critical processes. ### What the platform does * Turns Excel workbooks into governed processes. * Controls who can edit, submit, review, and approve. * Applies template-driven workflow rules across every process. * Produces controlled workbooks for contributors to complete. * Supports optional downstream publishing to Spark. ### How it fits together The platform is built around a few core parts: #### Templates Templates define the workflow. They set the steps, roles, actions, conditions, and lock behavior a process will use. Default options include simple submit, maker-checker, and Spark publishing flows. See [Default Templates](/control/workflow-templates/default-templates), [Create a new Template](/control/workflow-templates/create-a-new-template), [Actions](/control/workflow-templates/actions), and [Conditions](/control/workflow-templates/conditions). #### Processes Processes are live instances of a template. Each process has its own name, file, role assignments, and workflow history. Publishing a process creates the governed asset that users work with. See [Create A New Process - Coherent Assistant](/control/processes/create-a-new-process-coherent-assistant) and [Creating a New Process - Platform UI](/control/processes/creating-a-new-process-platform-ui). #### Controlled workbooks Controlled workbooks are the governed files users receive after publish. Templates determine what remains editable. Inputs can stay open while outputs, formulas, or static content stay locked. #### Users, teams, and roles Access is role-based. Administrators manage users and teams. Roles control which areas of the platform a user can access and what they can do inside a workflow. See [User Permissions](/control/user-management/user-permissions), [Team Permissions](/control/user-management/team-permissions), and [Roles](/control/user-management/roles). #### Coherent Assistant and Platform UI Teams can create processes in two ways. * Use **Coherent Assistant** to start from Excel and publish a controlled workbook directly. * Use the **Platform UI** to create a process through the Control wizard. Both routes use the same underlying template, role, and governance model. ### Typical workflow 1. An admin sets up users, teams, and roles. 2. A template admin defines or selects a workflow template. 3. A process owner creates a process from the platform or Coherent Assistant. 4. Contributors work in the controlled workbook. 5. Reviewers or checkers approve according to the template. 6. The platform records the workflow outcome and optional downstream actions. ### Where to start If you are new to the platform, start here: * [Quickstart](/control/get-started/quickstart) for the fastest path to a working setup. * [Create A New Process - Coherent Assistant](/control/processes/create-a-new-process-coherent-assistant) if your work begins in Excel. * [Creating a New Process - Platform UI](/control/processes/creating-a-new-process-platform-ui) if you prefer the web workflow. {% hint style="info" %} Use templates when you want consistency across many governed files. Use roles and teams when you want access to stay manageable as users change. {% endhint %} # Use Cases Coherent Control supports spreadsheet-driven processes where governance matters. These use cases show where the platform fits best. Each one highlights the control objective, the operational need, and the teams that benefit most.

Use case	Use Case Details
Spreadsheet Change Management Controls	Use this when a workbook drives a business process and changes need to be controlled rather than left to ad hoc editing. It covers the full lifecycle of a spreadsheet change: request, review, testing, approval, implementation, and rollback if needed. In practice, this is the control that helps teams prove that updates to critical Excel files were authorized, validated, and documented before release. It is especially relevant for regulated or business-critical models where even a small formula change can create reporting or operational risk.
Audit Trail and Versioning Practices	Use this when you need to answer the question “what changed, who changed it, and why?” This use case focuses on maintaining a reliable history of workbook versions and change events so that a reviewer or auditor can reconstruct the file’s evolution over time.
Access Control for Sensitive Spreadsheets	Use this when a spreadsheet contains confidential financial data, PII, or other restricted information and access needs to be limited. This use case covers how to control who can open, edit, share, or distribute a workbook, and it distinguishes between weak workbook/worksheet protection and stronger file-level encryption or SharePoint permissions.
Rater Management	Rater Management enables organisations to govern, approve, and deploy Excel-based rating models as controlled, production-ready assets, without removing teams from Excel. This use case is typically applied in: Insurance pricing and underwriting Actuarial model management Any workflow where Excel-based logic determines commercial decisions
Underwriting & Claims Workflows	Underwriting and Claims Workflow Management enables organisations to standardise, govern, and automate decision-making processes that rely on Excel-based logic, while maintaining full auditability and operational control. This use case applies to: Risk assessment and pricing in underwriting Claims triage, validation, and settlement calculations Workflows where the data conolidation from spreadsheet submissions is key to decision making
Finance Governance Processes	Finance Governance Processes enable organisations to control, standardise, and audit spreadsheet-driven financial workflows—ensuring accuracy, compliance, and accountability across critical processes such as reporting, forecasting, and regulatory submissions. This use case is particularly relevant where finance teams rely heavily on Excel for: Financial reporting and close processes Regulatory and statutory submissions Treasury, liquidity, and risk calculations

# Create A New Process - Coherent Assistant #### Entry Open the Coherent Assistant taskpane and click **Control**. On first use, the **Initial Control Screen** introduces the three benefits of Control.

Click **Take Control** to reach the **Process List**, then click **Create New** (from template) or **Create Custom**. **Before you start:** If the workbook is protected, unprotect it first. The Take Control button is disabled while any sheet or workbook protection is active. *** #### Process Creation Wizard The wizard walks you through five steps. *** **Step 1 — Select a Template**

For every role the template defines (e.g. *Auditor*, *Contributor*, *Owner*), add at least one user or team. *** **Step 3 — Process Information**

| Field | Required | Notes | | ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **Process name** | Yes | Must be unique in the tenant. | | **Description** | No | Shown in the process overview. | | **Tags** | No | Used to filter the process list. | | **Spark Folder** | Yes (If Upload to Spark action exists) |

Spark folder name.
It will be shown only if the selected template contains the Upload to Spark Action in any of Task

| | **Service Name** | Yes (If Upload to Spark action exists) |

Spark service name.
It will be shown only if the selected template contains the Upload to Spark Action in any of Task

| *** **Step 4 — Review Summary**

Review everything. Click **Publish** to create the process. The system will: 1\. Saves and uploads the workbook. 2\. Creates the process version in the backend. 3\. Downloads a new workbook copy and opens it. *** **Step 5 — Conversion (automatic)**

The **Convert Control File** step runs automatically in the new workbook: * Applies the lock type from the process definition based on Template (`non_input`, `non_static`, or `sheet`). * Protects the workbook and sheets (with optional password). * Sets workbook status to **Created**. * Opens the **Process Control Overview**. *** ### Creating a Controlled Instance from an Existing Process Use this flow to create a new controlled workbook linked to a process that already exists, without creating a new process definition.

#### Flow 1\. On the **Process List**, find the process (search or browse) and click it. 2\. Confirm the **Create Controlled Instance** dialog.

3\. The system saves your current workbook, then downloads and opens a **new** linked copy. 4\. Open Control in the new workbook — the **Link Control File** page runs automatically: * Fetches the process definition. * Locks and protects the workbook. * Sets status to **Created**. 5\. You land on the **Process Control Overview** ready to submit.

**Tip:** Suggested processes (shared with you by a previous submission's `suggest_group` action) appear at the top of the process list, making it easy to find the right process without searching. # Mapping Excel Files for Control Coherent Control adopts the same input and output mapping mechanism that is used widely on Coherent Spark. This mechanism allows users to map out input fields which can be edited in a locked-down version of a workbook to allow users to input data while keeping the formulas and underlying data protected. To learn more about how to map files and maintain this protection, please review the Coherent Spark input/output mapping documentation: {% content-ref url="/spaces/c7fek1ZgAUH5MA3m5pH8/pages/-MbpA0-hb5bjp7I5Avsa" %} [How to: Map inputs and outputs](/build-spark-services/map-inputs-and-outputs) {% endcontent-ref %} # Process Control Overview The **Process Control Overview** is the hub for every controlled workbook. It has three tabs. #### Overview Tab

**What you see:** * Process name and description (collapsible). * Role assignments and user permissions. * Available **task buttons** (e.g. Submit, Approve, Reject) — only shown when all conditions for that task pass. * **Submission Status Indicator** — tracks the current submission in real time. **Actions in the menu:** | Action | What it does | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Refresh** | Re-reads workbook hashes and re-evaluates which task buttons are available. Use this after editing cell values that are part of a condition. | | **Update process** | Opens the wizard pre-filled with existing data to publish a new process version. | | **Lock File** | Re-applies lock and protection (useful after temporarily unlocking to edit). | | **Reset Submission** | Clears the current chain and returns to the first task step. | *** #### Submissions Tab

* Lists all chains for this process group. * Toggle between **Pending** and **Completed** (Approved / Rejected). * Click **Open** on any submission to download that submitted file. * Scrolls infinitely for large histories. *** #### History Tab

Shows the current chain as a step-by-step timeline: * Each step: task name, completed by, date and time. * Click the comment icon to read the full note left at that step.

# Task Submission ### Task Submission #### How it works 1\. **Task buttons appear** only when all conditions for that task are satisfied - Configured in Template (like who you are, your role, previous steps completed, required cell values, workbook hash). 2\. Click the task button (e.g. **Submit**). 3\. If the task requires a comment, the **Task Comment Modal** opens.

4\. Enter your notes and click **Submit**. # Detailed Process Operations #### What happens under the hood | Step | What runs | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Re-validate conditions** | User, role, task-sequence, cell value, and hash conditions are checked again at the moment of submission. | | **Write Chain ID** | `CONTROL_CHAIN_ID` is written to workbook metadata to anchor the submission if it is first task executed. | | **Run task actions** | Actions execute in order: lock → save → protect → update\_status → email → etc. | | **Record chain** | The chain signature is posted to the backend with hashes and file path. | | **Deferred actions** | Any `suggest_group` actions run after the chain is saved (writes metadata for suggested processes and exports a copy). | #### Submission Status

| State | Meaning | | --------------- | ------------------------------------------------------------------------------------ | | **In Progress** | Actions are running — keep the taskpane open. | | **Success** | Chain recorded. A download link appears if the process is configured to provide one. | | **Failed** | A condition or action failed. The error message tells you exactly what to fix. | **Auto-reset on completion:** If the process is configured to clear the chain after the final step (e.g. after Checker approval), the workbook automatically resets to the first task — ready for a new submission cycle. # Updating a Process ### Updating a Process Updating publishes a **new process version** under the same group. Use this to add or remove role members, rename the process, or change its description. #### Steps 1\. From **Overview → action menu**, click **Update process**.

2\. The creation wizard opens pre-filled with current data. 3\. Edit **Roles** and/or **Process Information** as needed.

4\. On the **Archive Option** step, decide what happens to existing chains: * **Leave active** (default)Existing chains continue under the old version. * **Archive on update** Existing chains are archived when the new version publishes.

5\. Review the **Summary** and click **Publish**.

6\. The workbook metadata updates to the new process version ID and you return to Overview. # Resetting a Submission Reset clears the active chain from the workbook and returns it to the **first task step** — ready for a new submission cycle without creating a new workbook. #### Steps 1\. **Overview → action menu → Reset Submission.** 2\. Read the confirmation: existing chain history is removed from this file. 3\. Click **Reset**. #### What resets * Workbook is unprotected, `CONTROL_CHAIN_ID` is removed, then lock and protect re-run. * Overview returns to showing only the first task button. * Previous submissions already recorded on the backend are **not** affected. **Tip:** Before resetting, open the **Submissions** tab and download the current submission if you need a record of it. # Locking & Protecting the Workbook Lock and protection are applied automatically during creation, linking, and reset. You can also re-apply them manually. #### Lock Types | Lock Type | Cells that get locked | | ------------ | ------------------------------------------------------------- | | `non_input` | Everything **except** the `INPUTS` named range. | | `non_static` | Everything **except** constant (non-formula) cells. | | `sheet` | The used range on each visible, unprotected sheet. | | `range` | A specific named range or cell address defined in the action. | #### Protection * Workbook structure is protected (prevents sheet add/delete/rename). * Each sheet is protected individually, with configurable options (allow sort, format cells, etc.). * An optional password is stored encrypted in the process definition. # Process List ### Browsing the Process List

#### Finding a Process * **Search:** Type a name — results update as you type. * **Time groups:** Processes are grouped by age — Last 24 hours → Last week → Last month → Older. Suggested processes (from a `suggest_group` action) always appear at the top. * **Load more:** Scroll to the bottom to load the next page automatically. #### Filters

| Filter | Use when you want to… | | ----------------------------------- | -------------------------------------------------- | | **Hide processes with no activity** | Focus on active processes only. | | **Hide my processes** | See processes created by others. | | **Tags** | Narrow to processes tagged with specific keywords. | | **Templates** | Narrow to processes built from specific templates. | Click **Apply** — the list refreshes immediately. # Creating a New Process - Platform UI #### Entry Open the Platform web UI and navigate to **Control Dashboard**. Click on **Create Process** #### Process Creation Wizard The wizard walks you through six steps. *** **Step 1 — Select a Template**

Browse or search for a template (e.g. *Maker Checker*, *Simple Submit*). Each template defines the roles, approval steps, lock type, and actions the process will use. Click a template to select it, then click **Next**. * Templates load in pages of 20; scroll near the bottom to load the next page automatically. * The **Next** button is disabled until a template is selected. * Clicking **Cancel** resets the entire wizard and returns to the Control dashboard. *** **Step 2 — Template Details**

Review the full details of the selected template — name, short description, full description, and template type. Click **Back** to choose a different template, or **Next** to continue. *** **Step 3 — Assign Roles**

For every role the template defines (e.g. *Contributor*, *Auditor*, *Author*), add at least one user or team. Each role is shown in a collapsible accordion panel. *** **Step 4 — Process Information**

| Field | Required | Notes | | ---------------------- | ----------- | --------------------------------------------------------------------- | | **Process name** | Yes | Must be unique in the tenant. Checked in real time as you type. | | **Description** | Yes | Shown in the process overview. | | **Tags** | No | Used to filter the process list. | | **Spark Folder Name** | Conditional | Required only when the template includes a `publish_to_spark` action. | | **Spark Service Name** | Conditional | Required only when the template includes a `publish_to_spark` action. | *** **Step 5 — Review Summary**

Review all entered information across three cards: **Template**, **Process Information**, and **Role Assignments**. Click **Back** to edit any step, or **Next** to proceed to file upload. *** **Step 6 — Upload Process File**

Upload an Excel workbook (`.xlsx` or `.xlsm`) that will serve as the process template file. Drag and drop it onto the zone, or click **Select File** to browse. **Processing pipeline** — once a file is dropped, it moves through these stages automatically: | Stage | Description | | -------------- | ------------------------------------------------------------------------------------- | | **Uploading** | File is sent to the server. | | **Extracting** | File data is extracted (client-side for files < 10 MB; server-side for larger files). | | **Complete** | File is ready to publish. |

Once processing completes, click **Publish** to create the process group and process version in the backend.

On a successful publish, a confirmation screen is shown. You can **Download** the process file or click **Back to Dashboard** to return to the Control overview.

You need to download the file and opens with Coherent Assistant to make the file Control compliant. # Default Templates Coherent Control includes **7 default templates**: ### Maker Checker flow (3 Templates) The Maker can edit content in the workbook. Once submitted, a Checker must review and approve the changes before completion. **Maker Checker – Edit Inputs Only** The Maker can update mapped input fields only. Outputs, formulas, and static content remain locked. After submission, a Checker reviews and approves the changes before the process is completed. **Maker Checker – Edit Static Text Only** The Maker can update static text fields only. Inputs and outputs are locked. A Checker must review and approve these updates before completion, ensuring controlled narrative or documentation changes. **Maker Checker – Edit Everything** The Maker can edit all content in the workbook. Once submitted, a Checker must review and approve the changes before completion. This dual-control workflow supports auditability, reduces error risk, and strengthens governance. ####

### Simple Submit flow (3 Templates) **Simple Submit – Edit Inputs Only** Users can update input fields only. Outputs, formulas, and static content are locked. Once inputs are complete, the file can be submitted to create an auditable record of completion. **Simple Submit – Edit Static Text Only** Users can update static text fields only. Inputs and outputs are locked. This is typically used for commentary or documentation updates. Submission records completion for audit purposes. **Simple Submit – Edit Everything** Users can edit all content in the workbook, including inputs, outputs, formulas, and text. When complete, they submit the file to record completion and create an auditable timestamp of their work.

### **Publish to SPARK (1 Template)** **Edit Everything + Publish to SPARK** The Maker can edit all content in the workbook. Once submitted, a Checker must review and approve the changes before completion. Once approved, this template will automatically publish the service in Spark based on the folder and service selected in the process setup.

**Use these defaults as a starting point, then customize tasks, actions, and conditions as needed.** # Create a new Template ### Before you start * Login User into Platform UI * Make sure you have **TemplateAdmin** access. {% hint style="info" %} Please check with your Coherent Customer Success representative if you require this access. {% endhint %}

### Step 1: Go to Templates 1\. From the left menu, go to **Templates**. 2\. Click **Create Template** (top-right).

### Step 2: Fill Template Details In **Template Details**: * **Template Name** *(required)*: Use a clear name (example: “Loans – Maker/Checker – Edit Inputs Only”). * **Template Description**: 1–2 lines explaining when to use this template. * **Short Description**: A brief summary (max 100 characters). Click **Save Template Details**.

### Step 3: Build the workflow (canvas) You’ll land on the template builder page (canvas). At the bottom, use: * **Add Task** to add workflow steps * **Reset** to clear the canvas (if needed) * **Create Template** to publish/save when you’re done

### Step 4: Add tasks (one by one) Click **Add Task** → fill **Add New Task**: * **Task Name** *(required)*: The step name (example: “Upload file”, “Validate fields”, “Approve changes”) * **Button Text** *(required)*: What the user clicks (example: “Submit”, “Send for review”, “Approve”) * **Description** *(required)*: What the user should do in this step * **Enable Executables** *(optional)*: * Set **TRUE** only when you need executable-driven behavior. * **Important:** When **Enable Executables = TRUE**, the **Add Task Action** list is limited to **4 actions only**: * **Save** * **Update Status** * **Email** * **Publish to Spark** Click **Create** to add the task to the canvas. Repeat for each step in the process. ### Step 5: Configure template controls (right panel) On the right-side panel under **Template Configuration**, set: * **Reset File**: Shows a “Reset file” option in the control flow * **Require Maker Checker on Update**: Requires approval when updates are made * **Chain Update Confirmation**: Adds an extra confirmation step before applying updates * **Chain status on Update**: Choose the status that should apply after updates (example shown: “continue”) * **Roles**: Select roles to add (required if your workflow depends on role-based actions)

### Step 6: Save / publish the template When tasks and settings are complete: 1\. Review the workflow end-to-end (task order, labels, descriptions). 2\. Click **Create Template**. ### Quick checklist (admin QA) * Template name and descriptions are customer-friendly * Tasks have clear action verbs (Upload / Review / Approve) * Button text matches the action (Submit / Send / Approve) * Maker/Checker settings match your compliance needs * Roles are configured (if required) ### Troubleshooting **Can’t see “Create Template”** → check admin permissions. **Template doesn’t behave as expected** → review Require Maker Checker on Update Flag is FALSE # Actions ### Add Actions to a task (Task Properties) Actions are what happen when the user clicks the task button (example: lock, protect, save, update status). 1\. On the canvas, **click the task card** (example: “Submit workbook”). 2\. On the right panel, open **Task Properties → Details**. 3\. You’ll see the current list of actions for that task. 4\. Click **Add New Action**.

**Fill “Add Task Action”** In the **Add Task Action** popup, enter: * **Action Type** *(required)*: Pick one action from the dropdown. * If **Enable Executables = FALSE**, you’ll typically see options like: * Lock, Protect, Unprotect, Save, Remove Metadata, Update Status, Email, Execute XCall, Suggest Group, Publish to Spark * If **Enable Executables = TRUE**, the list is limited to **4 actions only**: * **Save, Update Status, Email, Publish to Spark** * **Action Name** *(required)*: A clear internal name (example: “Lock workbook”, “Send review email”). * **Supporting Text** *(optional)*: Helper text shown to the user (keep it short). * **Is Critical** *(optional toggle)*: Turn on if this action must succeed for the task to be considered successful. * **Payload Overridable** *(optional toggle)*: Turn on only if you want the payload to be editable/overridden. * **Error Message** *(optional)*: Message shown if the action fails (write it in customer-friendly language). Click **Add** to save the action.

####

#### Manage existing actions In **Task Properties → Details**, you can: * **Reorder** actions (drag handle) * **Edit** an action (pencil icon) * **Delete** an action (trash icon) # Conditions ### Add conditions to a task (Task Properties) Conditions control whether a task can be completed (example: only specific roles can submit, validations must pass). 1\. On the canvas, **click the task card** you want to control. 2\. On the right panel, open **Task Properties → Details**. 3\. Expand **Conditions** 4\. Click **Add New Condition**.

#### Fill “Add Task Condition” In the **Add Task Condition** popup, enter: · **Condition Name** *(required)*: A clear name for the rule (example: “Only checker can submit” or “Hash must be valid”). · **Condition Type** *(required)*: Select one from the dropdown. Options shown in your screenshots include: o **Role Condition** o **User Condition** o **Task Condition** o **Cell Value** o **Hash Validation** · **Target Description** *(optional)*: Short description of what the condition applies to (keep it simple). · **Operator Overridable** *(optional toggle)*: Enable only if you want the operator to be changeable. · **Error Message** *(optional)*: What the user sees if the condition fails (write it in customer-friendly language). Click **Add** to save the condition.

#### Notes (when Enable Executables is enabled) If you see a banner stating **“Some conditions are hidden because Enable Executables is currently enabled.”**, it means turning **Enable Executables = TRUE** limits which condition types are available. {% hint style="info" %} **Enable Executables** allows actions such as approval to be performed directly in the Control UI without requiring the Excel file to be downloaded and opened. {% endhint %}

#### Manage existing conditions In **Task Properties → Details → Conditions**, you can: · **Edit** a condition (pencil icon) · **Delete** a condition (trash icon) # User Permissions This guide explains how to manage users on the Coherent platform. It covers creating users, first-time sign-in, and assigning roles and teams to individual users. Administrator access is required to manage users, teams, and permissions. If you do not have administrator access and need changes, contact your tenant administrator. ### Permissions overview The **Permissions** section is where administrators manage who can do what. It has two pages: * **User Permissions** — assign roles and teams to individual users. * **Team Permissions** — create teams and assign shared roles to groups of users.

### Creating a user New users are created from the **Orchestration** page, which lists every tenant you administer. Each row in the list represents one tenant. The **Manage Users** link opens that tenant's user list.

To add a user: 1. On the **Orchestration** page, click **Manage Users** next to the tenant you want to add the user to. The **Users** list for that tenant opens. 2. Click **Create User** in the top right.

3. Fill in the new user's **First Name**, **Last Name**, and **Email**, then click **Create**.

The user is added to the tenant and an invitation email is sent to the address you provided. ### First-time sign in When a new user is invited, they receive a welcome email titled *Welcome to Coherent Spark*. The email contains a **Complete your registration** button and a link to their workspace.

To finish setting up the account: 1. Click **Complete your registration** in the email. This opens the account activation page. 2. Click **Click here to proceed**, then set a new password and click **Submit**. 3. Go to the workspace URL provided in the email and click **SIGN IN**.

4. Enter your email and password. After signing in, you are taken to the Dashboard.

Bookmark the workspace URL for future logins. If the invitation has expired, you can reset your password using the **Forgot password** link on the sign-in page. ### Managing user permissions The **User Permissions** page lists every user in the tenant along with the teams and roles they belong to.

#### Editing a user's teams and roles Click the edit icon next to a user to update their team and role assignments. On the edit screen, select the teams the user should belong to on the left and the roles they should have on the right, then click **Save**.

#### Viewing a user's teams Click **View User Teams** on any user row to see every team that user belongs to, along with when each team was last modified.

#### Viewing a user's roles Click **View User Roles** to see every role assigned to the user, together with a short description of what each role allows.

For team-wide access, see [Team Permissions](/control/user-management/team-permissions). For role requirements, see [Roles](/control/user-management/roles). # Team Permissions This guide explains how to manage teams on the Coherent platform. It covers creating teams, assigning shared roles, and reviewing team membership. Administrator access is required to manage users, teams, and permissions. If you do not have administrator access and need changes, contact your tenant administrator. ### Managing team permissions Teams let you group users together and assign roles to the whole group at once. The **Team Permissions** page lists every team in the tenant, along with its members and roles.

#### Creating a team 1. On the **Team Permissions** page, click **Create Team**. 2. Enter a team name and click **Create Team**.

On the next screen, select the users to add to the team on the left and the roles to assign on the right, then click **Save**.

#### Viewing a team's members Click **View Team Members** on any team row to see everyone who belongs to that team.

#### Viewing a team's roles Click **View Team Roles** to see the roles assigned to the team.

To manage roles for individual users, see [User Permissions](/control/user-management/user-permissions). For platform access by role, see [Roles](/control/user-management/roles). # Roles This guide explains how roles control access across the Coherent platform. Roles can be assigned directly to a user or through a team. Use [User Permissions](/control/user-management/user-permissions) for user-level access and [Team Permissions](/control/user-management/team-permissions) for shared team access. ### Roles and menu access The left-hand menu shows only the sections a user has permission to access. The required role for each menu item is: | Menu item | Required role | | -------------- | ----------------------------------------------- | | Dashboard | User | | Groups | User | | Workbooks | User | | Authors | User | | Scan & Catalog | User | | Control | User | | Suggestions | Suggestion Admin | | Templates | Template Admin | | Permissions | Tenant Admin | | Orchestration | Tenant Admin for the Coherent Admin tenant only | | Activity | Estate Analysis | | Forms | Estate Analysis | Every user needs at least the **User** role to access the platform. If no roles are assigned, the user will see a **No Access** screen when they sign in and will not be able to reach the Dashboard.

If you see this screen, contact your tenant administrator to request the appropriate roles. # Role Types Role types control what a user can do inside a specific process. They define whether someone can contribute work, review it, or manage the process end to end. These role types are different from platform access roles. Platform roles control which parts of the application a user can access. Process role types control what they can do once they are inside a process. The table below summarizes each role type and its scope.

Role Name	Role Description
Contributor	The contributor can view process configurations and create/update relevant chains in a process, but they can not update process configurations or view resources not relevant to their own chains.
Auditor	The auditor has full rights to view any information about the process, but can not make any changes to its state.
Owner	The owner has full rights over the control process. They are able to perform all operations on the group.

# Welcome [Coherent Spark](https://www.coherent.global/platform/coherent-spark) is the end-to-end solution to elevate and transform your Excel estate. Spark not only gives you unmatched intelligence with actionable insights, it converts your spreadsheet logic into production-ready APIs, significantly improving speed to market, auditability, control and governance, testing accuracy and more, all using your most familiar tool - Excel. ## Start here!


Get started with Spark	Go from Excel to API in just 5 minutes!	/pages/-MbjeVIhDMgL5AWwQZcF
Navigation	Take a tour of the Spark user interface.	/pages/hHOxuy8sDPBT98iSvpYO
Tenant administration	Help tenant administrators nhow to setup Spark for their users.	/pages/33gpuyYo8nxsTAs4aCgc

## Popular pages


How to: Map inputs and outputs	A more detailed guide about the `Xinput`and `Xoutput` functionalities of Spark.	/pages/-MbpA0-hb5bjp7I5Avsa
How to: Prepare an Excel file for Spark	A walkthrough with suggestions on best practices when setting up an Excel file for Spark.	/pages/vb2BW8nVwZKhEZPucYgb
Call Spark service APIs (`Xcall`)	Xcall allows Spark services to reference data and logic from other Spark services.	/pages/7SrkjU0Gy85eBQjw6qoP
Hybrid Runner	Deploy your logic on-premises, private clouds, or personal devices.	/pages/c1K85gVQxaAyBlgrHsDD
Execute API	Documentation for our main calculation API.	/pages/i1Gw4hnm5WLCg1qp8zNM

## Explore further


What's new?	An overview of recently released features and a full archive of historical release communications.	/pages/a4LuU4BUepL7MxTVeptJ
Coherent Assistant	A Microsoft Excel add-in that enables access to Spark functionalities.	/spaces/QQAtOKkd2V4rbmsT77rn
Build Spark services	Detailed explanations about the many options for building and managing services in Spark.	/pages/2mduKa5kkdyUoNDlldTD
Integrations	Technical information on how Spark can be deployed and used with other applications.	/pages/fkG1Pj66SalbN8YPgmIa
Spark APIs	Technical information about how to use Spark-generated APIs.	/pages/InncElujPaVzFMAT5QOa
Support	Answers to frequently asked questions and directions for contacting support.	/pages/09cCg2ownOzBA4wq7r40

# Get started in 5 minutes This guide will demonstrate how easy it is to convert an Excel file to code and have a working API ready that is ready for integration! We will use a basic example to create a volume of a cone API using Spark. You can extend this example to the most complex Excel spreadsheets in the same way! ## Map inputs and outputs in Excel ![](/files/dOIm7XJDv1HpfkhQDE5c) Spark uses [Named Ranges](https://support.microsoft.com/en-us/office/define-and-use-names-in-formulas-4d0f13ac-53b7-422e-afd2-abd7ff379c64) to define the inputs (radius, height) and outputs (volume) from this calculation. 1. Open Excel and setup the formulas for the volume of a cone. 2. Use the Name Box to map `Xinput_r` and `Xinput_h` as inputs into the volume calculation. Spark reads the prefix `Xinput_` and identifies these Named Ranges are inputs into the calculation. ![](/files/zN5XfI47L4PZtCQXvA0E) 3. Use the Name Box to map `Xoutput_V` as an output of the volume calculation. Spark reads the prefix `Xoutput_` and identifies this Named Range as an output of the calculation. Spark is able to automatically process the formulas in the Excel workbook! ![](/files/felkrYv51twKcIcsz88G) 4. Open the *Name Manager* by clicking the **Formula** tab in the Ribbon and choosing **Name Manager**. In total, there should be 3 Named Ranges, `Xinput_r`, `Xinput_h`, `Xoutput_V`. ![](/files/23KVMA3IdoJe6vPe14pZ) ![](/files/wxFLS6WHC9AbDsbM54Ty) 5. Save the file or alternatively use the pre-prepared file for the next step. {% file src="/files/WEwnX0YLrryoD4GFrQnf" %} ## Create a folder The first screen after logging into Spark is the [Home](/navigation/home) screen. On this screen Folders can be created to organize the different Spark Services (converted Excel files). ![Enter some details to create a folder](/files/gYLFi8L4EzktWueymSoD) 1. Create a folder to store this Excel file. 2. Enter a name for this folder. 3. Choose a Category which relates to the types of Excel files that will be uploaded to this folder. 4. Provide a description of this folder. 5. As an optional step, a Cover Image can be added as well. 6. Click **Create**. 7. The [Folder overview](/navigation/folder-overview) screen will be displayed. ## Add a service In Spark, a service is created when an Excel file is converted to code and there is a corresponding API created to execute the convert code.

1. From the [Folder overview](/navigation/folder-overview) screen, click on **New service** to open the upload modal. 2. Click on **Browse** to select a file, or drag and drop your Excel file inside the modal to upload.

3. Enter an alternate *Service name* to refer to this file using a different name in Spark. 4. A *Version label* can make it easier to differentiate multiple service versions later. 5. Once the conversion is complete, click on **Publish** to complete the "Excel-to-code" conversion and API generation! The logic in the Excel spreadsheet is now in a Spark service! 6. You will be taken to the [API Tester](/navigation/api-tester) to test the converted code ## Test the converted code and execute the API

The [API Tester](/navigation/api-tester) can be used to test the converted code and the [Execute API (v3)](/spark-apis/execute-api/execute-api-v3) which performs the Spark calculations. 1. On the left API request panel, the `height` and `radius` are identified as inputs from the mapping done earlier. 2. Enter different values for the `height` and `radius` of the cone. 3. Click **Submit** to submit an API request. 4. On the right API request panel, the resulting `Volume` of the cone will be returned! 5. The *JSON view* and *Raw view* provides information useful for developers integrating to Spark's automatically generated APIs. ## Explore more features! * For business users, there is a further explanation of the Excel Spark mappings beyond `Xinput` and `Xoutput` in [How to: Map inputs and outputs](/build-spark-services/map-inputs-and-outputs). * For Administrators, read how to setup your tenant in [Tenant administration](/tenant-administration) and [Identity and Access Management](/identity-and-access-management/recommendations). * For Developers, learn more about: * Automatically generated calculation APIs in [Execute API](/spark-apis/execute-api). * [Authorization - Bearer token](/spark-apis/authorization-bearer-token). * [Authorization - API keys](/spark-apis/authorization-api-keys). # What's new? | UAT release | Production release | | ------------- | ------------------ | | July 27, 2026 | August 10, 2026 | We've got a helpful safeguard for you this month: Spark now checks for mapping changes when you upload an updated file, giving you an early heads-up before anything reaches your integrations. And don't miss our latest customer spotlight and case study with Óptima Mayores, whose two-person IT team runs an entire business on Spark. *This release includes updates available in both UAT and Production.* ## Mapping differences highlighted on upload When updating Spark services, Spark will inform you if the uploaded file includes new or removed mappings. This provides an additional check to the user to inform of any consequential changes to their Spark integrations and testing. Spark will also suggest users to choose a major version update to indicate that there are incompatible API changes. This follows [semantic versioning](https://semver.org/) guidelines.

## Notable Enhancements * [Testing Center](/navigation/testing-center) testbed results now include expanded tables for CSV downloads. * [Coherent Assistant](https://docs.coherent.global/assistant/) Testbed feature now supports running `Xsolve` to when making Excel-calculated testbed results. This enables verification between Excel and Spark results that include solve functions. * [Service Documentation](/navigation/service-documentation) indicates last modified date including for any service versions that have been edited. * Improvements to [Service Documentation](/navigation/service-documentation) and [Options](/navigation/options#deployment-request) screens. * New [Neuron](/build-spark-services/neuron) version with formula updates. * Security patch updates to address vulnerabilities, ensuring enhanced protection and stability of our systems. #### A Note for [Transforms API](/spark-apis/transforms-api) users Please review the [scheduled updates](/spark-apis/transforms-api/transform-types/update-roadmap) to the JSON and XML parsing packages. Updates to dependent packages make take place on short notice for any vulnerability fixes. {% hint style="warning" %} The commonly used [JSONata](https://jsonata.org/) package in the [JSONtransforms](/spark-apis/transforms-api/transform-types/jsontransforms) will have a major update in the September release. {% endhint %} ## How a two-person IT team runs an entire business on Spark

Óptima Mayores serves customer projections, partner portals, and internal workflows from models deployed on Spark. Go-live took four days, reporting that used to eat a full day now takes five minutes, and every API call is traceable to the channel that made it. {% embed url="" %} ## Version number `v8.58.2` # Release schedule We release a new version of Spark every month with new features, enhancements and fixes! Releases become available to customers first via the UAT (User Acceptance Testing) environments and are then released to the production environments approximately two weeks later. | UAT release | Production release | | ------------------ | ------------------ | | June 22, 2026 | July 13, 2026 | | July 27, 2026 | August 10, 2026 | | August 24, 2026 | September 7, 2026 | | September 28, 2026 | | # Release history Please visit the subpages for the historical release updates. * Hybrid Runner release history can be found in [Hybrid Runner release history](/hybrid-runner/hybrid-runner-release-history). * Neuron release history can be found in [Neuron release history](/build-spark-services/neuron/neuron-release-history). # 2026-06 | UAT release | Production release | | ------------- | ------------------ | | June 22, 2026 | July 13, 2026 | We cleaned up API key management this release. Keys now live in one simple view, you can edit and rotate them in a couple of clicks, and nothing changes about how your existing keys work. ## Easy API Key Management

We've simplified the user interface for API keys to make it much easier to manage API keys! * View all API keys without any grouping hierarchy. By default, the keys that will expire soon will be displayed first. * Previous API key group names are now associated to each API key name. * Descriptions can give more context to API keys. * Edit existing keys instead of making new API keys. * Delete any test or unnecessary API keys. * Rotate API keys with 2 clicks! * Maintain the existing granular permission management. Learn more in our API key documentation [Authorization - API keys](/spark-apis/authorization-api-keys). {% hint style="info" %} API keys will continue to function the same way after this user interface change! {% endhint %} ## Notable Enhancements * Updates to [Model Context Protocol (MCP)](/integrations/model-context-protocol-mcp) tools include new tools to list, run, compare, download from Testing Center. * [Coherent Assistant](https://docs.coherent.global/assistant/) new UDFs to validate connection to Spark. * [API Call History](/navigation/api-call-history) has an updated filter selection menu to reduce previous extra clutter. * Edit service version has some adjustments to remove extra steps during version updates. * New denylisted login message. * Security patch updates to address vulnerabilities, ensuring enhanced protection and stability of our systems. #### A Note for [Transforms API](/spark-apis/transforms-api) users Please review the [schedule updates](/spark-apis/transforms-api/transform-types/update-roadmap) to the JSON and XML parsing packages. Updates to dependent packages make take place on short notice for any vulnerability fixes. ## Version number `v8.56.1` # 2026-05 | UAT release | Production release | | ------------ | ------------------ | | May 26, 2026 | June 8, 2026 | Big improvements to the Testing Center this month. If you've been comparing testbed results, the whole experience just got faster and more customizable — including a new Excel fast export (beta) that handles larger outputs without the wait. ## Updates to testing center comparisons

Our Testing Center enables the application of models against large datasets for testing and modeling purposes. With multiple testbed results, users can compare results to better understand changes in model outputs. We've added new capabilities to testbed comparisons to make it faster and easier to customize the comparison output. * New *Excel fast* (beta) option that writes out larger outputs faster than the *classic Excel* option. * Ability to retain only mismatches in the comparison to more quickly produce a report checking if two results are exactly the same. * Skip downloading of inputs to reduce the size of the report. * Customize the number of records and heading order. ## Notable Enhancements * Selective webhook events! When defining webhooks, you can choose which events should fire a webhook call. This makes the webhook much less chatty and easier to consume. * Further updates to Homepage and Folder overview pagination. * Action items updated in API Call History, Service Library, and Version Overview. * Further improvements to batch throughput. * Faster access to the backend storage of Spark services. * `Xreport` new API option for image border fix. * `Xreport` fix for invalid date format. * Security patch updates to address vulnerabilities, ensuring enhanced protection and stability of our systems. ## Version number `v8.54.1` # 2026-04 | UAT release | Production release | | -------------- | ------------------ | | April 27, 2026 | May 11, 2026 | This month we are releasing a long-requested feature to edit existing Spark service versions. We also have a number of enhancements that improve the performance and usability on the platform. ## Edit existing Spark service versions Make changes to a Spark service even after it has been published! Spark services have historically been "locked-in" after a version has been created. Any changes to an existing version would require a new version to be created. In this update, we include the ability to edit a service version without having to create another version. This makes it easy to add information that was missed at the time of upload or test different configuration values. This supplements the ability to delete service version from the prior release. ## Notable Enhancements * Improved Xcall performance if a specific service version number is specified. * Even faster publish time for Spark services. * API Call History quicker user interface and query response for complex queries. * API Tester OpenAPI code snippets are much more comprehensive. * Testing Center Testbed Comparison is moved to a background activity to minimize impacts to Spark session. * Batch improved stability for high chunk counts. * API Call History and Testing Center, Excel downloads that include expanded tables now have support for long input and output names. * Coherent Assistant service upload includes additional fields for release notes and description. * Homepage and Folder overview UI adjustments for consistent pagination. * MCP authentication flow is greatly simplified and MCP tool updates. See [Model Context Protocol (MCP)](/integrations/model-context-protocol-mcp) for more details! * Fixed an issue with API keys including `tenant-admin` group. Note this is not a recommended pattern but partially supported for compatibility. * Security patch updates to address vulnerabilities, ensuring enhanced protection and stability of our systems. ## Version number `v8.52.0` # 2026-03 | UAT release | Production release | | -------------- | ------------------ | | March 30, 2026 | April 13, 2026 | Big update this month — we've made batch processing faster, given you more control over service versions and API call history, and shipped a handful of improvements across Spark Shell and the Coherent Assistant. We're also retiring a few older features as better alternatives take their place, and we're excited to share a new strategic partnership with Indico Data. Details on all of it below. ## What's New in Coherent ### 📑 Delete Service Versions * To facilitate management of Spark service versions, we’ve now included the ability to delete service versions through the user interface. This can help to clean up messy services while retaining the functionality of the "keeper" versions. * We are also working on the ability to edit service versions! Look out for this in a future release! ### 🔑 Deployment request access management * Spark provides an interface for users to submit a [Deployment request](/ci-cd/deployment-request) to their internal systems from the [Options](/navigation/options) page. By default, access is granted to all users who can login to Spark. * We have added a new configuration in the [Options](/navigation/options#tenant-configuration) section to manage which users are able to submit this request to improve controls around this process. ### 🚀 Batch execution unleashed * Spark's [Batch APIs](/spark-apis/batch-apis) enable widescale processing of Spark services on large datasets. We have enhanced our implementation to significantly increase the default buffers that are used to manage the inflow and outflow of data. For large jobs, this makes it much easier to manage the flow of data in and out of Spark leading to faster completion times. * Learn more on how to [*Run High-Volume Models with Coherent's Batch APIs*](https://www.coherent.global/blog/run-high-volume-models-with-coherent-batch-apis). ### 🔍 API Call History search and download updates * There may be many instances when Spark is called repeatedly for one quotation due to evaluating different options and benefits. When downloading the [API Call History](/navigation/api-call-history), a lot of extra data may be included when only the latest quotation is relevant. * We have included a new filter for the [API Call History](/navigation/api-call-history) which will keep the latest combination of `source_system`, `call_purpose`, `correlation_id`. This reduces the amount of data to be transferred and processed by the end user performing the analysis! * In addition to this for downloading a set of API calls to Excel, we have introduced a new *Fast beta* option which should offer improved download speeds.nd work ### 🗃️ Spark Shell browser * Spark [SHELL](/assistant/shell/what-is-shell) is a feature in the [Coherent Assistant](https://docs.coherent.global/assistant/) that introduces control and management over Excel documents. * In this update, we have incorporated a Shell browser to view all of the created Shell documents. This greatly simplifies the process of distributing the latest Shell documents to users. Instead of using network storage, SharePoint, or even emails, simply click the Shell tile in the [Coherent Assistant](https://docs.coherent.global/assistant/) to see all the Shells available. Upon selecting a Shell, the Excel file will be downloaded and ready to be used. * Read more about *When Your Excel Logic is Ready, But You Don't Have a Front-End* in [our blog post](https://www.coherent.global/blog/when-your-excel-logic-is-ready-but-you-dont-have-a-front-end) on Spark Shell benefits. ## Notable Enhancements * Our [Analyze service with AI](/build-spark-services/analyze-service-with-ai) can work across multiple Spark service versions to enable comparison or change analysis. Open the Analyze Service functionality for any `2` Spark services (or versions) and start chatting! * Updates to Upload service journey to reduce the time taken to publish a service. * Improve the speed of uploads by skipping the step used to insert a cover sheet into the uploaded Excel document. This can be managed in the [Options](/navigation/options#tenant-configuration). * Reconfiguration of service and version properties. * [Coherent Assistant](https://docs.coherent.global/assistant/) has additional fixes for logout issues encountered by some users. * Update to the [JSONtransforms](/spark-apis/transforms-api/transform-types/jsontransforms) to support longer request times. * Fix for `Xreport` formatting issues. * [Update](https://docs.coherent.global/build-spark-services/neuron/neuron-release-history) to [Neuron](/build-spark-services/neuron) Excel-to-code compiler for better formula compatibility. If you use [Data Tables](https://support.microsoft.com/en-us/office/calculate-multiple-results-by-using-a-data-table-e95e2487-6ca6-4413-ad12-77542a5ea50b) that include dynamic headers, we recommend updating to the latest version of [Neuron](/build-spark-services/neuron). * Security patch updates to address vulnerabilities, ensuring enhanced protection and stability of our systems. ## Version number `v8.50.1` # 2026-02 | UAT release | Production release | | ----------------- | ------------------ | | February 23, 2026 | March 9, 2026 | New month, new release. This edition covers the latest Coherent Assistant, Spark Shell, and Neuron updates, plus a step forward in Spark API documentation. ## Notable enhancements #### 🖱️ Documentation * We now have [OpenAPI specifications](https://spec.openapis.org/oas/v3.1.1.html) for many of the Spark APIs available in our [documentation](https://docs.coherent.global/spark-apis/spark-openapi-specification) site. OpenAPI is a standard method of documenting APIs to make them more easily consumable through external integrations. * The Spark [documentation](https://docs.coherent.global/spark-apis/spark-openapi-specification) site also renders the specifications in a user-friendly interface with the ability to test endpoints online. #### 👥 Coherent Assistant * Spark Shell: Fix an error relating to login session timeout. * Spark Shell: Import inputs of source data where fields are not present in target file. * Spark Shell: Improved handling for Shell 2.0 Xcall formulas failed to execute. * Spark Shell: New configuration to block submissions that fail Excel formula based validation. * Spark Shell: Publish service folder list will show favorite folders first * Spark Shell: Operators and Creators have logout and refresh Xcall buttons. #### 💡 Neuron compiler enhancements * Implementation of the `LONGTEXT()` and `SCAN()` functions. * Fixes for `LAMBDA()` functions. * Fixes for Excel Data Table calculations. * Fixes for `Xrichoutput` being inconsistent with prior versions. * Function enhancements and fixes: `IFS()`, `ISREF()`, `MAP(INDEX())`, `MMULT()`, `SEQUENCE()`, `SUM(IF())`, `TEXT()`. * Performance enhancements and bug fixes. #### 🖥️ System improvements * Security patch updates to address vulnerabilities, ensuring enhanced protection and stability of our systems. ## Version number `v8.47.0` # 2026-01 | UAT release | Production release | | ---------------- | ------------------ | | January 19, 2026 | February 2, 2026 | Happy New Year from Coherent! We're kicking off 2026 with a new beta: Excel Workbook Analyst, an AI-powered assistant designed to help you explore and analyze Excel workbooks with ease. Whether you're auditing complex models or trying to understand legacy logic, Workbook Analyst provides instant visibility into workbook structure, formulas, and potential issues - saving hours of manual inspection. ## In Beta: Excel Workbook Analyst

Excel makes it easy to model complex calculations and business logic. But over time, those workbooks can become difficult to maintain, review, and evolve. Excel Workbook Analyst helps by enabling you to: * Inspect workbook logic and receive clear summaries and explanations of the key components, including VBA * Identify potential risks and problem areas within a workbook * Ask natural-language questions about how a workbook works and receive suggested improvements Unlike traditional Excel tools that focus on surface-level formulas or static scans, Workbook Analyst goes deeper by leveraging Coherent’s core technology for understanding Excel logic at scale. The result is a fast, intuitive experience—available directly on Excel files already uploaded to Spark. #### How to use Workbook Analyst Select the relevant Spark service containing your Excel file and choose Analyze service with AI. Workbook Analyst opens in a new window with a structured, navigable view of the Excel workbook alongside an interactive chat experience making it easy to explore what the file does and how it could be improved. #### Interested in joining the beta? Contact your Coherent rep to learn more. ## Notable enhancements #### 🖱️ User experience * When creating or updating a Spark service, custom semantic versions can be selected by using the *Custom* version option. * When creating or updating a Spark service, Release notes and Description can be defined during the upload in the *Notes* tab. * Homepage and Folder Overview screen have a refreshed list view. * For API calls that use [Xsolve](https://docs.coherent.global/build-spark-services/other-mapping-options/solve-functions), when using the API Call History, Download as Excel feature, the calculated solve result is embedded into the file, making it easier to interpret the result. * Fixed an issue where clicking links to Spark when logged out would direct to an error page. #### 👥 Coherent Assistant * [Coherent Assistant](https://marketplace.microsoft.com/en-us/product/office/wa200006757?tab=overview) will promptly inform users when they have been logged out. * Spark Shell functionality to import inputs from another Shell file. * Spark Shell has better messaging for operators if the user access the wrong environment. #### 🚀 Service execution * The latest version of Neuron, our Excel-to-code engine, enables much faster processing of [Excel Data Tables](https://support.microsoft.com/en-us/office/calculate-multiple-results-by-using-a-data-table-e95e2487-6ca6-4413-ad12-77542a5ea50b). * Improvements to service execution times. * Execute API will echo additional parameters into the response when provided. * Better handling of user permissions in Xcall for batch and testing center. * [Nodejs22](https://docs.coherent.global/spark-apis/transforms-api/transform-types/nodejs22) transform includes more options to customize the HTTP status code in the response. #### 🔑 Security * The Spark User menu includes a menu item to access the Keycloak console for managing Identity and Access Management. * Updates to the Allowlist functionality to improve handling of IP addresses. If your organization uses this feature, we suggest revisiting the Allowlist settings on your tenant. #### 🧮 Testing Center * Testing Center null handling is more aligned with API Tester behavior. * Improvements to Testing Center handling of data types. * Initial beta preview of Testbed result aggregation. #### 📶 Artificial Intelligence * Initial release of our [Model Context Protocol (MCP)](/integrations/model-context-protocol-mcp) server to support agentic interfaces with Spark. #### 🖥️ System improvements * Security patch updates to address vulnerabilities, ensuring enhanced protection and stability of our systems. ## Version number `v8.45.0` # 2025-11 | UAT release | Production release | | ---------------- | ------------------ | | 24 November 2025 | 08 December 2025 | We've been working hard for exciting new features in future releases. ## Notable enhancements #### 🧮 Testing Center * Improved read performance from the Testing Center database to improve download stability. * Batch and Testing Center are more responsive when canceling jobs. #### 🔗 Integrations * JSON transformation functionality supports larger request and response body sizes. * Execute API additional request\_meta parameters are echoed back to the response\_meta. This helps to confirm that the settings have been properly received by the API. #### 🖥️ System improvements * Security patch update to address vulnerabilities, ensuring enhanced protection and stability for the system. ## Version number `v8.41.1` # 2025-10 | UAT release | Production release | | --------------- | ------------------ | | 27 October 2025 | 10 November 2025 | We've been hard at work this month making useful improvements! We have a new data retention feature that automatically removes older log data from Spark systems. ## New: Data retention policies for API Call History and Event Log At Coherent, your data matters to us and we want to give you more control over how it’s managed on our platform. Spark already lets you upload, download, and delete key data assets. With this release, we’re introducing data retention settings for API Call History and Event Logs. We can now help you to configure how long these records are kept. After the retention period, entries will be automatically removed from Spark’s databases. This helps your organization stay aligned with internal data policies and security requirements, while keeping your workspace clean and efficient. Want to enable this feature for your Spark tenant? Just reach out to your Customer Success representative. ## Notable enhancements #### 🧮 Testing Center * Download testbed results faster with the new *Excel (fast)* download. This is a beta feature made available to all users that enables downloading large testbed results much faster. * Improved terminology in the Testing Center to be more consistent across the user experience. #### 🐚 Spark Shell updates * Spark Shell can be configured to display the `call_id` after a successful submission. #### 😎 User interface improvements * Updated list view across the homepage, folder overview, and testbed screens to be more intuitive to use. * Improved handling of downloaded documents. If the file was generated but you missed the download, the download can be accessed from the Background activity menu within 15 minutes without having to regenerate the entire file. * Setting permissions should be much faster for folders with many services and/or users. * The Service Documentation screens have some updates to improve usability. #### 🧠 Neuron and `Xcall` improvements * Neuron compiler enhancements, updates and fixes across a number of Excel functions including better performance for Lambda functions. * Improved handling of `Xcall` request meta fields. * Services that use `Xcall` can now return the proper `call_id` reference from the downstream API call. This allows better management and fetching of data from downstream API calls. * `Xcall` can now be debugged using the new API request parameter `debug_xcall`. When this is used, the API response will include a trace of the `Xcall`s made during the execution of the API call. Learn more in the [API documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v3). #### 📤 Transform updates {% hint style="warning" %} There is a change to the `JSONtransforms` which will return the `Content-Type` header properly as `application/json` rather than `text/plain`. This may potentially impact current integrations that check the `Content-Type` field. {% endhint %} * The newest version of the JSONata ([2.1.0)](https://www.npmjs.com/package/jsonata/v/2.1.0) package is available in `JSONtransforms_v1.0.0` and `Nodejs22_v1.0.0`. ## Version number `v8.39.0` # 2025-09 | UAT release | Production release | | ----------------- | ------------------ | | 15 September 2025 | 06 October 2025 | This month, we've added a new File Compare tool to Coherent Assistant (no more tedious spreadsheet checks) and expanded Spark's connection options. ## New: Instantly Compare Excel Workbooks

Comparing spreadsheets manually takes time—and it’s easy to miss important changes. With File Compare, now available in Coherent Assistant, the process is fully automated. Our tool instantly detects all differences in values, formulas, and text between two workbooks and generates a detailed report that highlights each change. That means you can verify updates at a glance and collaborate with confidence. **Your privacy is our priority!** Because all processing happens locally on your machine, your files never leave your computer. Try File Compare in Coherent Assistant [now](https://appsource.microsoft.com/en-us/product/office/wa200006757?tab=overview)! ## New: External Connections with Spark #### 🔗 XConnector now available via Hybrid Runner Our [XConnector](https://docs.coherent.global/xconnector/introduction-to-xconnector) feature allows Spark to connect to external services during calculations - unlocking use cases like accessing network databases or external resources. Previously, this required an active connection with the Coherent Spark environment. With this release, [XConnector](https://docs.coherent.global/xconnector/introduction-to-xconnector) is now supported via the [Hybrid Runner](https://docs.coherent.global/hybrid-runner/introduction-to-the-hybrid-runner), enabling local deployments to benefit from these capabilities too. #### 🧠 Nodejs22 transforms support for external services The [Nodejs22 transform](https://docs.coherent.global/spark-apis/transforms-api/transform-types/nodejs22) lets users write JavaScript to orchestrate Spark APIs and build custom API flows. We’ve now added support for calling external services directly from these transforms. This opens up exciting possibilities to combine external data sources with Spark services - creating more dynamic solutions for complex integration requirements. ## Other Enhancements * The Excel file comparison process has been reworked to support larger more complex files. * Systematic test case generation will generate fewer permutations by default for numeric ranges. ## Version number `v8.36.0` # 2025-08 | UAT release | Production release | | -------------- | ------------------ | | 18 August 2025 | 01 September 2025 | This month we have released some meaningful enhancements across different areas of the platform. ## Feature Focus: Testing Center — Systematic Test Case Generation ### Single Change Permutation Mode The Systematic test case generation feature in Spark enables users to create test cases that cover test cases across all your input parameters. In this release, we’ve introduced a new **Single Change Permutation** mode to enhance the flexibility of test case generation. Unlike the original combination system — which creates all possible permutations of input values — this mode generates test cases where **only one variable changes at a time**, keeping all others constant.

### Benefits * Enables more controlled, isolated testing. * Allows for **wide coverage** of input variations. * Keeps the **number of test cases low**, reducing redundancy and execution time. * Useful for pinpointing the impact of individual variables. ### How It Works To use the Single Change Permutation mode, start by selecting it in the “Define your testbed” section. Once selected, you’ll add and configure your input fields and values—just like you would in the original All Permutations mode. The system then uses your default values as the baseline and generates new test cases by changing one value at a time across your selected inputs. This results in a clean, easy-to-compare set of test cases that provides wide coverage while keeping the number of variations low. ## Release notifications

Learn more about new Spark features directly within our web interface! With each new release, a notification will appear in the bottom right corner of the screen. Upon clicking *Learn more*, a sidebar will appear with a summary of the new features in the release! If you have dismissed the notification by accident and would like to review the release messages again, you can click the User menu and choose *What’s new*. ## Notable enhancements * **Testing Center**: The *Run Testbed* journey has UX improvements for more consistent terminology and clearer indicators of successful or failed testbed runs. * **API Tester**: The *Raw* view now includes a **Copy** button to make it easier to copy and edit API requests and responses. * **Import and Export API**: * A new `/status` endpoint allows you to check job progress. * Export API is now significantly faster for services with many versions. * Export API provides more detailed timing information for service exports. * **API Call History**: A new endpoint allows access to individual call details using the `call_id` reference. * **Multi-Factor Authentication**: MFA for user accounts can now be enabled through the user management interface. ## Version number `v8.34.0` # 2025-07 | UAT release | Production release | | ------------ | ------------------ | | 21 July 2025 | 04 August 2025 | This month's release includes a number of new feature updates inspired by your feedback. This note covers what’s coming in both the UAT and Production releases. Don't feel like reading? Watch the short video wrap-up below: {% embed url="" %} ## New Features & Enhancements ### Feature focus: API Call History

The API Call History records all of the API Calls made to Spark, enabling audit, review, and analysis of past executions. For this month’s release we’ve made some often requested enhancements and more for the API Call History: * API Calls sometimes may lead to errors or warnings due to use of default values, invalid input values, or even calculation errors. Identify API Calls that returned errors or warnings during execution using the ⚠️ ⛔ symbols. These API calls can also be filtered and downloaded for further examination. Note this will only apply to new API calls post this release. * Review table inputs and outputs with ease using the *Download as Excel file (Expanded tables)*. Table inputs and outputs are displayed on separate worksheets which makes it easy to analyze complex call history for models with complicated table structures. * API Call History now will record if the `excel_file` parameter is provided in an API Call. * Addressed a bug with filtering the API Call History for `call_purpose` and `source_system`. ### Download Service Update

We’ve improved the design of the *Download service* feature to make the different options more clear! Most users likely will want to download the *Original workbook* but can use the Coherent Assistant option if you would like to explore the file in the add-in right away. ### Make AI integrations easier We’ve been looking at how we can make integrating an application to Spark easier. In this release we have made some enhancements to make AI consumption of Spark services easier: * API Tester Swagger documentation can be accessed without authentication if the Spark service is made public. * API Tester automatically generated API documentation now also includes information about the Validation API. The [Validation API](https://docs.coherent.global/spark-apis/validation-api) includes details about single value inputs which can facilitate the development of a UX around a Spark service. ### Other Notable enhancements * The Testing Center *Systematic test case generation* now includes an option to *Clear variations* in order to reset the number of variations back to 1. This makes it easier to build up your custom variations if there are too many variations created by default. * The Event viewer shows all the recent activities on an environment. When initially released, it defaulted to filtering one folder at a time. We have updated the feature such that viewing events across all folders is now the default. * Further UI updates to improve the experience for users with limited permissions. * Performance improvements in the Coherent Assistant Testbeds functionality. * Security patch updates to address vulnerabilities, ensuring enhanced protection and stability for the system. ## Version number `v8.32.1` # Tenant administration {% hint style="info" %} The user administration may differ if using [Single sign-on](/identity-and-access-management/single-sign-on). {% endhint %} This guide provides guidance and recommendations on how to set up Spark user groups, users, and API keys. * This content mainly relates to the pages [Manage users](/tenant-administration/manage-users) and [Authorization - API keys](/spark-apis/authorization-api-keys). * Please read our [Get started in 5 minutes](/getting-started-in-5-minutes) page before using this guide. ## Relevant Spark terminology * First check if your tenant has been set up as a [Private tenant](/tenant-administration/private-tenant). This is denoted in the [Navigation menu](/navigation/navigation-menu#user-menu). * In a Shared tenant, all users have access to all folders and services within a tenant. * In a [Private tenant](/tenant-administration/private-tenant), users have restricted access to folders and services: * After an Excel file has been uploaded to Spark and the logic is converted to code, it is referred to as a service. * Folders are used to organize multiple services together. * User permissions can be applied to the folder level. ## Add customized user groups {% hint style="info" %} This is only relevant if your tenant has been set up as a [Private tenant](/tenant-administration/private-tenant). {% endhint %} An organization may contain different teams who should have separate access to services in Spark. Some examples could include: * Finance team and marketing team manage calculation and logic. * American and Canadian branches of an organization. * A research team working on a sensitive project. * An audit team that needs only `read` permissions. If your tenant has been set up as a [Private tenant](/tenant-administration/private-tenant), separate user groups can be created to separate access different groups of users. 1. Follow the steps in [Manage users](/tenant-administration/manage-users#add-user-groups) to create the relevant user groups representative of the organization. Custom user groups must begin with `user:`. Examples could include: `user:audit`, `user:canada`, `user:finance`. ## Add tenant administrators You will likely need to have multiple tenant administrators who can also manage [Active services](/tenant-administration/active-services), [Authorization - API keys](/spark-apis/authorization-api-keys), [Manage users](/tenant-administration/manage-users#user-groups), and[Manage users](/tenant-administration/manage-users#users). 1. Follow the steps in [Manage users](/tenant-administration/manage-users#add-users) and create an account for the other tenant administrators. * These accounts should be created with membership in `user:pf` and `tenant-admin` user groups. * If this is a [Private tenant](/tenant-administration/private-tenant), it is recommended that all `tenant-admin`s are also added to the `supervisor:pf` user group. This enables `tenant-admin`s to see all the folders within your tenant. This is not enabled by default. ## Add supervisor users {% hint style="info" %} This is only relevant if your tenant has been set up as a [Private tenant](/tenant-administration/private-tenant). {% endhint %} There may be a need for intermediate-level users who don't have tenant administrator privileges but can manage all folders on a tenant. In this case, supervisor users can be created. This could for example be where an IT team is responsible for account administration and a team leader needs to be able to manage different folders in Spark. 1. Follow the steps in [Manage users](/tenant-administration/manage-users#add-users) and create an account for supervisors. * These accounts should be created with membership in `user:pf` and `supervisor:pf` user groups. ## Add additional users 1. Follow the steps in [Manage users](/tenant-administration/manage-users#add-users) and create an accounts for Spark users. * All users must be members of `user:pf` to login to Spark. * If this is a [Private tenant](/tenant-administration/private-tenant), users can also be assigned to the user groups added earlier. 2. Tell teams about this [user guide](https://docs.coherent.global/) and [Coherent Academy](https://coherentacademy.coherent.global/)! ## Add folders with specific permissions {% hint style="info" %} This is only relevant if your tenant has been set up as a [Private tenant](/tenant-administration/private-tenant). {% endhint %} 1. If user groups have been created in the previous step, it may help to initialize working folders for the organization with different permissions. 2. Follow the steps in [Home](/navigation/home#add-a-new-folder) to create additional folders. 3. Follow the steps in [Private tenant](/tenant-administration/private-tenant#set-permissions-on-folders-via-api) to add the customized team groups and the appropriate permissions. * For example, this could be a *Finance projections* folder with permissions assigned to `user:finance` users. * Only add `user:pf` to a folder in a [Private tenant](/tenant-administration/private-tenant) if all users should be able to access this folder. ## Add API keys for calling Spark APIs API Keys can be used to integrate with the [Execute API](/spark-apis/execute-api) and other management APIs in [Permissions - Features permissions](/spark-apis/authorization-api-keys/permissions-features-permissions). * In Spark, you must create an API key group first. * [Authorization - API keys](/spark-apis/authorization-api-keys#api-key-groups) can contain multiple [Authorization - API keys](/spark-apis/authorization-api-keys#api-key-instances). * A key instance would correspond to an API key that is used for authentication. * Multiple key instances are useful for managing key rotation, where the to-be-deactivated, expiring key and the next API key have an overlap for continuity. * An API key group represents the combined access rights of multiple user groups. Follow the steps in [Authorization - API keys](/spark-apis/authorization-api-keys#add-api-key-groups) to create the first API key group. 1. If this is a Shared tenant, we recommend making the initial API key one that can access all Spark services. Do so by assigning the user group `user:pf` to the API key group. 2. If this is a Private tenant, then assign the appropriate user groups created earlier. # Manage users {% hint style="info" %} Coherent's recommendation is to integrate Keycloak, our Identity and Access Management (IAM) with your Identity Provider (IdP). This provides the best security for user accounts. See [Identity and Access Management](/identity-and-access-management/recommendations) and [Benefits of IdP versus local accounts](/identity-and-access-management/benefits-of-idp-versus-local-accounts). This functionality may be disabled if [Single sign-on](/identity-and-access-management/single-sign-on) is enabled. {% endhint %} ## User groups Tenant administrators (`tenant-admin`s) can create user groups, which act like teams where different users are grouped together if they perform similar actions. For example, the Product team can be a part of the same user group, responsible for adding and updating the Excel files on Spark. User groups can control access to Folders, if part of a [Private tenant](/tenant-administration/private-tenant). * In a *Shared tenant*, where every user has access to all folders and services within a tenant, the relevant user groups are `tenant-admin` and `user:pf`. * In a [Private tenant](/tenant-administration/private-tenant) where users have restricted access to folders and services: * The relevant user groups also include `supervisor:pf` and any other user groups the administrators may want to create, such as regional or functional teams. * User groups can also define permissions for [Authorization - API keys](/spark-apis/authorization-api-keys). ### Default user groups | User group | Description | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `supervisor:epos` | This is only used by Coherent Flow tenants. | | :police\_officer: `supervisor:pf` | This user group by default has access to all Folders and Services. | | :star2: `tenant-admin` |

Realm administrator that can manage User, Groups, Clients, Roles and Realm/Tenant.
In a /pages/xnvs0k85jDD6K3EkGvfi, tenant-admins cannot see all Folders and Services unless they added to the supervisor:pf group.

tenant-admins can also use APIs to access all objects within Spark.

| |

tenant-moderator

Realm Moderator that can manage only User and Groups.
This group can remain unused.

| | `tenant-viewer` |

Realm Viewer it can only view Users and Groups.
This group can remain unused.

| | `user:anonymous` | This is only used by Coherent Flow tenants. | | `user:coherent.forms` | This is only used by Coherent Flow tenants. | | `user:epos` | This is only used by Coherent Flow tenants. | | :star: `user:pf` | Access to this user group is mandatory for a user to login to Spark. | ### View user groups 1. Login using `tenant-admin` credentials. 2. Choose **Options** from the [Navigation menu](/navigation/navigation-menu#user-menu). 3. In the left-hand navigation that appears, select **User groups**. 4. Click **View users** to see all the users who are members of each user group. ### Add user groups {% hint style="warning" %} Newly created user group names should begin with the prefix `user:` or `supervisor:`, for example `user:NewUserGroup`. {% endhint %} {% hint style="info" %} `supervisor` users are able to manage the users for folders they have access to. When a folder is created, `supervisor` user groups are also assigned access by default. {% endhint %} 1. Follow [#view-user-groups](#view-user-groups "mention") to arrive at the *User groups* screen. 2. Click on **Add user group**. 3. Enter the required information. 4. Existing [#users](#users "mention") on Spark can be added to the user group. 5. Click **Submit** to finish adding the user group. ### Edit user groups 1. Follow [#view-user-groups](#view-user-groups "mention") to arrive at the *User groups* screen. 2. Click on the "three-dot menu" and select **Edit user group**. 3. A similar screen to [#view-user-groups](#view-user-groups "mention") appears. 4. Click **Submit** to finish making changes. ### Delete user groups * Follow [#view-user-groups](#view-user-groups "mention") to arrive at the *User groups* screen. * Click on the "three-dot menu" and select **Delete user group**. * Any permissions related to the deleted user group will no longer apply. ## Users `tenant-admin`s also have the ability to add users to their Spark environment. Users can be managed from the *Users* page inside Spark. Individual users added to Spark will then have the ability to log in and start creating APIs. ### View users 1. Login using `tenant-admin` credentials. 2. Choose **Options** from the [Navigation menu](/navigation/navigation-menu#user-menu). 3. In the left-hand navigation that appears, select **Users**. 4. In the three-dot menu for each user, click **View users** to see all the users who are members of each user group. ### Add users {% hint style="warning" %} `user:pf` is a mandatory user group for users to login to Spark! {% endhint %} 1. Follow [#view-users](#view-users "mention") to arrive at the *Users* screen. 2. Click on **Add user**. 3. Enter the required information. 4. Users can be added to the relevant user groups. `user:pf` is required to access Spark!. 5. Alternatively, user permissions can be copied from an existing user. 6. Users can also be setup to use Multi-Factor Authentication to login. See [Multi-Factor Authentication (MFA)](/identity-and-access-management/multi-factor-authentication-mfa) for more information. 7. There is an option to choose between sending the user an invitation link or generating a password. 8. Click **Submit** to finish adding the user. ### Edit users 1. Follow [#view-users](#view-users "mention") to arrive at the *Users* screen. 2. Click on the "three-dot menu" and select *Edit user*. 3. A similar screen to [#add-users](#add-users "mention") appears. 4. Click **Submit** to finish making changes. ### Deactivate users {% hint style="info" %} Users cannot be deleted from Spark in order to support internal audit and tracking of events in Spark. {% endhint %} 1. Follow [#view-users](#view-users "mention") to arrive at the *Users* screen. 2. Click on the "three-dot menu" and select **Deactivate user**. 3. The user account will be deactivated and no longer able to access Spark. # Private tenant {% hint style="warning" %} A tenant can only be configured to be a private tenant at the initial setup. Once a tenant is either private or shared, it cannot be converted to another type. This setting can be verified in the [Navigation menu](/navigation/navigation-menu#user-menu). {% endhint %} In a private tenant, folders created on Spark are only visible to the user who created them until explicitly shared with other users and user groups. The sole exception is for members of the `supervisor:pf` group, who have access to see all Folders and Services in Spark by default. The private tenant feature is best used in conjunction with custom [user groups](/tenant-administration/manage-users#user-groups) that are aligned with regional or functional responsibilities in an organization. ## Spark entity permission types Create, Read, Update, Delete and Execute permissions that are applied to users and users groups for a folder affect the actions that can be taken on the folder and the services within them. The table describes the required permissions to perform key functions in Spark. {% hint style="info" %} The table below is meant to be read from left to right. Most actions require combined permissions. For example to delete a folder, you need both `Read` and `Delete` permissions. Depending on your browser and screen, some of the columns in the table may be hidden. Scroll right at the bottom of the table ➡️ to see the complete details. {% endhint %}

Entity	Action	Create	Read	Update	Delete	Execute

Folder	Clone		✅
	Download		✅
	Delete		✅		✅
	Edit		✅	✅
	Favorite	✅	✅	✅
	New folder	✅	✅
	View		✅

Service	Add service	✅	✅	✅
	Add version	✅	✅	✅
	Analyze with AI		✅
	API Call History		✅
	API Tester		✅			✅
	Compare versions		✅
	Delete		✅		✅
	Delete service version		✅		✅
	Deployment Request		✅
	Download		✅
	`/batch` `/execute` `/metadata` `/SPARK_XCALL` `/validation`		✅* see #execute-only-permissions			✅
	Edit service version		✅	✅
	Favorite	✅	✅	✅
	Recompile	✅	✅	✅
	Restore version	✅	✅	✅
	Update service properties		✅	✅
	View		✅

Transform	Add	✅	✅	✅
	Delete		✅		✅
	Execute		✅			✅
	Edit		✅	✅
	Update		✅	✅

Testbed	Add additional test cases		✅	✅
	Aggregate	✅	✅			✅
	Delete		✅		✅
	Download		✅
	Favorite	✅	✅	✅
	Run	✅	✅			✅
	Test case generation	✅	✅			✅
	Upload	✅	✅
	View		✅

Testbed results	Compare results		✅
	Delete		✅		✅
	Download		✅
	Upload test results	✅	✅
	View		✅

Document section	Add	✅	✅	✅
	Delete		✅	✅	✅
	Edit	✅	✅	✅
	View		✅

Document	Delete		✅		✅
	Download		✅
	Move to	✅	✅	✅
	New document	✅	✅	✅
	Update		✅	✅
	View		✅

### supervisor role When a new folder is created, the user group `supervisor:pf` is assigned to the folder by default with all of the permission types applied. This means by default, users included in the `supervisor:pf` user group have access to all folders and services in Spark. If the user who creates the folder is a member of other user groups, the supervisors of those user groups will also be granted access to manage this folder. For example, if a user is a member of `user:team3` creates a folder, the folder will also be accessible by the user group `supervisor:team3`. ### `execute` only permissions It is possible to make calls to `/batch`, `/execute`, `/metadata`, `SPARK_XCALL()`, `/validation` with only `execute` permissions and without `read` permissions. This requires configuration from Coherent. Contact [Support](/support/support) for more information. ## Set permissions on folders In private tenants, permissions for folders can be assigned: 1. [#directly-to-user-accounts](#directly-to-user-accounts "mention") 2. [#to-user-groups](#to-user-groups "mention") 3. [#to-api-key-groups](#to-api-key-groups "mention") 4. [#to-service-accounts-oauth2-client-credentials](#to-service-accounts-oauth2-client-credentials "mention") ### Directly to user accounts To assign permissions, you must either be the owner of the folder or a member of the `supervisor:pf` group. Follow these steps: 1. Click on the folder, then click on the "three-dot menu" to access the options and select *Set Permissions*. 2. Type in the email address of the account you would like to add. If configured, you will also see that you can choose a user or group from the typeahead list. Set the necessary permissions for the user. 3. Click **Done**. 4. The user account specified in Step 3 will now have access to the folder. ### To user groups To assign permissions, you must either be the owner of the folder or a member of the `supervisor:pf` group. To create a user group, you must be a member of the `tenant-admin` group. 1. Navigate to the menu on the top right corner (button with your initials) and select *Options*. 2. In the menu bar on the left-hand side, select *User groups* and click on *Add user group*. 3. Enter a group name. The user group name MUST start with the prefix `user:`. For example, `user:example-user-group`. Fill in the description, add all necessary users, and click **Submit.** 4. Navigate back to the folder, then click on the triple dot action button to access the folder options and select *Set permissions*. 5. Type in the user group you would like to add. If configured, you will also see that you can choose a user or group from the typeahead list. Set the necessary permissions for the user. 6. Click **Done**. 7. The user group added should now have access to this folder. ### To API key groups To create an API key group, you must be a member of the `tenant-admin` user group. Prerequisite: a user group exists and is assigned to a folder ([#to-user-groups](#to-user-groups "mention")). 1. Navigate to the menu on the top right corner (button with your initials) and select *Options.* 2. Go to the page *API keys*. 3. Click *New API Key group*. 4. Enter the key group name, description, the user group you assigned to the folder from [#to-user-groups](#to-user-groups "mention"), and click on **Create**. 5. You can now generate a key in the API key group and make calls to the services within the folder using the `x-synthetic-key` request header. (See [Authorization - API keys](/spark-apis/authorization-api-keys)). ### To service accounts (OAuth2 client credentials) Service accounts can also be given permissions directly, without the need for "dummy" users. This is especially useful for CI/CD operations, or tasks involving interactions with non-public APIs. For complete instructions, see [Client credentials grant (OAuth 2.0)](/identity-and-access-management/client-credentials/client-credentials-grant-oauth-2.0). ## Set permissions on folders via API The use of this functionality requires using an access token with sufficient privileges, either [Authorization - Bearer token](/spark-apis/authorization-bearer-token) or [Broken mention](broken://pages/Dx1VW4Wsqbw72hKR5spG). 1. First get the ID of the folder. 1. Send a `POST` request to the following endpoint: `https://excel.{environment}/api/v1/product/list`. 2. In the request headers, include in `Authorization` a bearer token. 3. Include the following JSON payload in the request body: ```json { "search":[ { "field": "name", "value": "{Folder}" } ] } ``` 4. Copy the `id` from the response body after sending the `POST` request above. It should look something like this: { ```json "data": [ { "id": "a8d98bbf-e5aa-44ce-ad90-cebe728c7776" "name: "Demo", ... } ] ``` 2. To assign permissions to the folder: 1. Send a `POST` request to the following endpoint: `https://excel.{environment}/api/v1/entitypermission/setentitypermission`. In the request headers, include in `Authorization` a bearer token. 2. Include the following JSON payload in the request body:

{
        "entityID": "{Folder_ID}",
        "remove": {true or false based on if you want to assign these rights},
        "create": {true or false based on if you want to assign these rights},
        "update": {true or false based on if you want to assign these rights},
        "execute": {true or false based on if you want to assign these rights},
        "read": {true or false based on if you want to assign these rights},
        "members": "{List of users, groups, credentials separated by comma}"
      }

* If the member is created from [Client credentials](/identity-and-access-management/client-credentials), then use the Client Credential which should include the `service-account` prefix. 3. An example of the JSON payload is as follows: ```json { "entityID": "a8d98bbf-e5aa-44ce-ad90-cebe728c7776", "remove": true, "create": true, "update": false, "execute": true, "read": true, "members": "bob@amunet.com.au, user:pf, service-account-cc-folder-level" } ``` 3. After completing the steps above, you should observe the changes in the folder you've chosen in the *Set permissions* dialog. # Manage tenant settings From the Tenant Configuration page, tenant administrators (`tenant-admin`s) can conveniently configure their tenant settings. This space currently includes settings such as enabling public visibility for Spark service APIs, permission controls, and IP allowlisting. The Tenant Configuration page can be found in the [Options](/navigation/options) menu. ## Set *General configurations* ### Choose the Public API visibility Spark services have private visibility by default. By checking **Enable 'Public' API visibility settings**, this will turn on the ability to create public Spark services. *Public* Spark services do not require any authentication to execute. For more detailed instructions, see [Authorization - Public APIs](/spark-apis/public-apis). ### Choose the Neuron compiler for newly uploaded services This defines a version of [Neuron](/build-spark-services/neuron), Spark's Excel-to-code compiler to use for all new services. This setting can be overridden on upload. * *Stable Latest*: Spark will use the latest stable release of Neuron available. * *Release Candidate*: Spark will always use a release candidate release if available. A release candidate is a version of Spark that may contain enhancements and fixes that were not included in the latest stable version. If there are no release candidate versions available, Spark will use *Stable Latest*. When a service is compiled using a *Release Candidate*, subsequent updates will also be performed using *Release Candidate*. * In addition to these options, a specific version of Neuron can be used for all newly uploaded services. This setting can be overridden on upload. Also refer to the [Neuron](/build-spark-services/neuron) [Neuron release history](/build-spark-services/neuron/neuron-release-history). ### Choose the Neuron compiler version for additional service versions When [Folder overview](/navigation/folder-overview#add-new-version) is applied to a service, there is also an option to define which version of Neuron to use for a service update. This will only apply to any new services that are uploaded to Spark. This setting can be overridden on upload. * *Tenant Default*: Spark will use the version of Neuron defined above for newly uploaded services. * *Maintain Version*: Spark will try to use the same version of Neuron as the previous version of the service. If Spark cannot determine what version of Neuron was used on the previous version of the service, then Spark will use the **Stable Latest** version of Neuron. * *Stable Latest:* Spark will use the latest stable release of Neuron available for the update. * *Release Candidate*: Spark will use the release candidate version (see definition above) if available. Also refer to the [Neuron](/build-spark-services/neuron) [Neuron release history](/build-spark-services/neuron/neuron-release-history). ### Set the Coherent Assistant Hybrid Runner URL When this is defined, Coherent Assistant will direct API calls and execution to your hybrid runner URL or [XConnector](/xconnector/introduction-to-xconnector) instead of the Coherent Spark systems. ## Define Explainer domain URL in *Explainer configurations* Explainer is an application from Coherent that can make dynamic insurance front-ends using Microsoft Excel. Define the Explainer Domain URL (the root domain for Explainer user interfaces) here. Replace the default URL with your own if you need to host the Explainer UI in your own domain. Please note clicking **Save** while the URL input is empty will repopulate the previously saved URL. ## Assign permissions through *Features permissions* Spark services can be called using [Authorization - API keys](/spark-apis/authorization-api-keys). For better security, by default API keys cannot also be used to call other microservices that serve Spark services. If you are looking to perform more of the service management or to access advanced features, the *Features permissions* allow API keys to also be used to call backend microservices. Each row represents a feature permission which can be thought of as folders of endpoints grouped by function. More information can be found in [Permissions - Features permissions](/spark-apis/authorization-api-keys/permissions-features-permissions). ## Restrict Spark access via IP allowlisting Check the box labeled *Enable IP allowlisting* to restrict access to the Spark UI and Spark service APIs to specific IP addresses. This restricts access to this tenant only for specified IP addresses, reducing the possibility of unauthorized access. 1. Enter the name to assign to the IP address under *Rule name.* 2. Insert the IP address in IPv4, IPv6, or in CIDR notation standard for specifying blocks of IP addresses under *IP address*. 3. Add other relevant information under *Description*. (This column is optional) 4. Click **Save** when completed. Note that in order to prevent any account lockouts, credentials that include the `tenant-admin` group including accounts, API keys, or credentials, are not restricted from the IP allowlisting. ## Manage tags Tags can be useful to categorize the service versions uploaded to Spark. Within *Tenant configuration* tenant administrators can enable tagging and define the universe of tags. Tags can be used associated with a service either during the service upload or modified in the [Service Documentation](/navigation/service-documentation). ## Configure webhooks Spark can send a webhook even when particular actions occur in Spark. More information can be found in [Webhooks: Connect Spark with external systems to automate workflows](/integrations/webhooks-connect-spark-with-external-systems-to-automate-workflows). # Active services {% hint style="warning" %} This feature is only enabled on certain environments and tenants. Please contact [Support](/support/faq) for more information about this feature. {% endhint %} With the Active services functionality enabled Spark enables different statuses to be assigned to services to control whether they can be used and their visibility to other users. If Active services are enabled on your tenant, Spark services can be managed with 3 different statuses: * *Active*: This service can be used and connected with API integrations. An active service is denoted with a green dot 🟢. * *Inactive*: This service cannot be used and integrations are disabled. * They also be hidden from certain dialog * Inactive services are also from the Spark dashboard views. * *Archived*: Similar to inactive, yet furthermore only `tenant-admin`s can view and manage these services. By default, newly uploaded Spark services are set as *Active*. ## Deactivate or archive a service {% hint style="info" %} The ability to deactivate or archive services is limited to `tenant-admin`s by default. This can be modified through configuration by Coherent to enable for all users. {% endhint %} 1. Identify an *Active* service either from within a folder or the [Options](/navigation/options#service-library). You may need to adjust the filtering to make *Inactive* or *Archived* services visible. 2. Click on the "three-dot menu" and click on *Deactivate service* or *Archive service.* 3. When navigating through the different pages for an *Inactive* or *Archived* service, it will indicate that many of the standard functionalities have been disabled. ## Activate a service The ability to activate services is limited to `tenant-admin`s only. This will re-enable the ability to use the standard features of a service. 1. Identify an active service either from within a folder or the [Options](/navigation/options#service-library). 2. Click on the "three-dot menu" and click on *Activate service.* 3. The service will then again be indicated with a green dot 🟢. # Navigation # Login and logout ## **Log in to** Spark 1. Access Spark with the provided login URL. Most links to Spark should be constructed as `https://spark.{environment}.coherent.global/{tenant}`. A tenant is a separated part of the computing environment allocated to one client. 2. If your organization has enabled Single Sign-On (SSO) you will see another button below *Log in*. Click that button to enter Spark. 3. Otherwise, enter your Email and Password. This account should be assigned either by the Spark tenant administrator from your organization or provided by the Coherent team. 4. To save the login details for future logins, check the box next to *Remember me*. 5. Click **Log In**. 6. The browser will navigate to the [Home](/navigation/home) page. {% hint style="info" %} If Single Sign-On (SSO) has been enabled for your tenant, there may be another button under **Log In**. Clicking that button should automatically continue the login process. {% endhint %} ## **Log out of** Spark 1. Click the user menu (the top right corner) on the header navigation and click Logout. 2. Spark will give a warning message that confirms the logout action. ## **Reset password** 1. If the password has been forgotten or the password reset email has expired, visit the login URL and click *Forgot password*. 2. Follow the steps to receive a verification code to the registered email address to create a new password. If the *Forgot password* was not received, please check the following: 1. Please check the correct email address was used as the user name. 2. Check the Spam / Junk / Custom mail folders. 3. Add `no.reply@coherent.global` to any email allowlists. 4. Request another password link from the login page by clicking *Forgot Password*. {% hint style="info" %} **Note:** The password to be set should have a lowercase, an uppercase, a number, and a special character, and contain a minimum of 8 characters. {% endhint %} # Home ## Home screen folders The Home screen is used to view and manage the Folders in your Spark tenant. Folders are used to organize the different converted Excel services in Spark. For a first-time user of Spark, there will not be any Folders displayed on the home screen. ## Change how folders are displayed The home screen's display of the folders can be modified by a number of options in the action bar. * *Search by folder name*: Begin typing a search term and the list will automatically update * *Sort by*: Allows different sorting options, including date modified, A-Z, and Z-A. * *Categories*: Allows filtering of the folders based upon the Category defined when the Folder is created or modified. * *Favorite folders*: When enabled, the screen shows only folders set by [#favorite-folder](#favorite-folder "mention"). * *Card/List view*: The default "Card view" shows folders as large image tiles. "List view" is more compact and displays one folder per line. * In "Card view", additional information about a folder can be seen when hovering over the card. This includes whether or not the services in the folder are active/inactive (see [Active services](/tenant-administration/active-services), for more detail). ## **Add a new folder** See [Get started in 5 minutes](/getting-started-in-5-minutes) for an overview of this process. 1. Click **New folder** in the action bar. 2. See [Get started in 5 minutes](/getting-started-in-5-minutes#create-a-folder) to see more information about creating a folder. ### Upload a previously downloaded folder The backend for this feature is based upon the [ImpEx APIs](/spark-apis/impex-apis). An exported ZIP file from the [Export](/spark-apis/impex-apis/export) API can also be uploaded here. 1. If a folder had previously been downloaded, click **New Folder.** 2. Switch to the *Upload folder* tab. 3. Select the ZIP file to upload. ## Other folder actions Additional actions can be performed on the folder from the three-dot menu. ### Favorite folder When a folder is created by a user, it is automatically marked as a favorite for them. A folder can also be set as a favorite by choosing "Favorite this folder". Similarly, a folder can be unfavorited by choosing "Unfavorite this folder". Favorite folders can be filtered on the home screen using the toggle. ### Edit folder Edit the category, cover image, and description of the folder. ### Clone folder **Clone folder** makes a copy of the folder with a new name. Similar to [#download-folder](#download-folder "mention"), Spark will only retain the latest version of each service. ### Download folder Spark makes it easy to package the services within a folder together to move between environments. The ZIP file can be imported back to Spark as described in [#upload-a-previously-downloaded-folder](#upload-a-previously-downloaded-folder "mention"). The implementation uses the same backend as the [ImpEx APIs](/spark-apis/impex-apis). {% hint style="warning" %} When downloading a folder, Spark will only retain the latest version of each Spark service. {% endhint %} ### **Delete folder** Before a folder is deleted, Spark will request confirmation for the delete action. When deleting a folder, all services and documents in the folder will be deleted. It is not possible to delete only 1 version of a service. {% hint style="warning" %} Folders can only be deleted if the user has permission to do so! {% endhint %} ### Set permissions If your tenant is set up as a [Private tenant](/tenant-administration/private-tenant), access to this folder can be managed in this menu. More information can be found in [Private tenant](/tenant-administration/private-tenant#set-permissions-on-folders). # Navigation menu ## Return Home from any screen Click the Coherent logo in the top left to return [Home](/navigation/home). ## **Manage background activities** A *Background activity* is initiated when users run a task that potentially take a while to complete. These are shown in the Background activity dropdown box. This will include a list of in progress, canceled, or failed tasks. The most common *Background activity* tasks are from the [Testing Center](/navigation/testing-center) where test results are processed. ## Change the Spark user interface language ![](/files/YD8M7vFDg810lJPwxO88) the *Language switch* can be used to choose between different available languages. ## User menu The User menu is visible when clicking your initials from the top right of the screen. Below your name you will also see: your login email, tenant name, whether or not you are using a [Private tenant](/tenant-administration/private-tenant) or Shared tenant, which user groups you belong to, and your current [UTC offset](https://en.wikipedia.org/wiki/UTC_offset). | Option | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Options | Navigates to the [Options](/navigation/options) administrative screens in Spark. | | Bearer token | Provides a [Authorization - Bearer token](/spark-apis/authorization-bearer-token) which is useful for quick integration testing. | | Dashboard view | Navigates to a dashboard of Spark service usage with an emphasis on [SHELL](/assistant/shell/what-is-shell). | | What's new | Displays a sidebar with summarized [What's new?](/whats-new) content from the latest Spark release | | About Spark | Shows the Spark version number which may be useful for [Support](/support/support). | | User guide | Navigates to [Welcome](/). | | Coherent Academy | [Coherent Academy](https://coherentacademy.coherent.global/) is the place to participate in guided training courses and earn Spark certifications. | | Keycloak console | Linke to the Identity and Access Management console used with Spark. This option is only available to tenant administrators. | | Support | Support is a link to the [Service Desk Portal](https://coherentglobal.atlassian.net/servicedesk/customer/portal/5) to submit tickets to the Spark support team. | | Logout | [Login and logout](/navigation/login-and-logout#log-out-of-spark). | --- [Next Page](/llms-full.txt/1)