> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/readme/design/design-best-practices.md). # Design best practices The following are design best practices that you should consider when building an integration. ### Integration categories Your integration should be categorized as one of the following: * Import events as incidents * Threat intel feeds * Analysis & SIEM * Authentication * Data enrichment and threat intelligence * Database * Endpoint * Forensics & malware analysis * Messaging * Utilities * Vulnerability management We recommend you review [common use cases](/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/readme/design/use-case-design-for-cortex-xsiam.md) to help categorize your integration. ### Data clarity The data returned to the analyst should be as clear as possible. For example, you should convert Epoch timestamps, decrypt data if necessary, etc. If you return IDs, return the original asset name, category type, group name, etc. Additionally, make the parameters and command descriptions as descriptive as possible. Users should be able to understand what the command does and any argument/parameter defaults, maximums, minimums, etc. Use the same names as used by your product, when possible. Your product UI should serve as a baseline for your human readable output. ### DBotScore When mapping a score to DBotScore, stay as close as possible to the integrated product scoring thresholds and categorization. These are usually documented or can be found in the UI of the integrated product. DBotScore reputation includes the following scores: 0 – unknown, 1 – good, 2 – suspicious, 3 – bad. Give users a threshold argument to enable customers to override and implement alternate scoring logic. Specify the score thresholds and DBotScore mapping to the integration documentation. Set [generic reputation commands](/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/integrations-and-scripts/developing/generic-commands.md) that indicate the entity reputation such as `!url`, `!ip`, `!file`, etc. . ### Global context Global context outputs are important. When an analyst executes commands/playbooks, global context gives them the option to receive information from multiple integrated products. You can also use global context outputs for DBot scoring and global indicators. ### Commands Follow these best practices for commands. * Use the following naming convention for commands: `PRODUCTNAME-OBJECTNAME-ACTION`. This structure makes it easier for the analyst to find the right object in the UI. * Command arguments should be snake case and lower case. For example, `argument_name`. * If a command takes more than a few seconds to execute (for example, vulnerability scan, complex query, or file detonation in sandbox), add a polling playbook. If you implement a polling playbook, include a `status` command as well. * When a command supports filtering results by time, use start and end time parameters (if supported by the UI), and a time frame parameter that accepts inputs such as “4 days ago” or “5 minutes ago”. ### Backward compatibility Cortex XSIAMcomponents, such as playbooks, rely on previous inputs. To avoid breaking backward compatibility, keep the old context, add new paths as needed, and update the outputs accordingly. If a command needs major modifications, deprecate the command and create a new one. ### Limitations * The logo must be under 10kB. Use the company logo, not the product logo. * If the result contains more than 50 entries, limit the context size. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/readme/design/design-best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.