> 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/integrations-and-scripts/create-a-sample-integration/define-sample-integration-settings.md).
# Define sample integration settings
When you click on the **BYOI** button, you enter the Cortex XSIAM IDE. By default, the HelloWorld integration template is loaded. You will replace it with the integration you create. This includes replacing the existing HelloWorld integration settings with new settings, and deleting unused parameters or arguments.
Behind the scenes, the settings you enter are saved in a YAML file which you can export and import. To learn more about Cortex XSIAM integration YAML files, see [Integration metadata YAML file](/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/integrations-and-scripts/components/integration-metadata-yaml-file.md).
As an example, we are going to create an English to Yoda translator, which translates normal English into the way Yoda, the Star Wars character, speaks. This is a simple integration that lets us explore important aspects of integration development. With our integration, we can try calling an API, parsing data, and posting it to the War Room. We will use the Yoda-Speak translate API available at [FunTranslations](https://funtranslations.com/api/yoda).
**Basic settings**
In the **Basic** section, name the integration, add a description, choose a category, and set several additional options.
1. Under **Integration Name**, replace the `HelloWorld` integration name with `Yoda Speak`.
2. Under **Description**, include basic information about the integration, common troubleshooting steps, and any required setup instructions. For the purposes of this tutorial, enter `Creating an Integration, we are`.
3. Under **Category**, select `Utilities`. See the full list of available [categories](/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/readme/design/design-best-practices.md).
4. Add a **Logo**. You can drag and drop the logo or click the box to open a file browser to select a file for upload.
Logo requirements:
* No larger than 10KB
* Transparent background
* PNG format
{% hint style="info" %}
### Note
The **Fetches alerts** checkbox tells Cortex XSIAM that the integration runs periodically to ingest events and create alerts in Cortex XSIAM. Our Yoda Speak integration does not need to fetch incidents, so make sure this checkbox is empty. While we don’t need this feature for our Yoda Speak integration, fetching alerts is an essential part of many integrations. There are additional options available here including external schema support and long running integration, but these are less commonly used.
{% endhint %}
**Parameters settings**
This section lets you set parameters that can be used across all commands in the integration. Some common parameters include the API key used for communicating with the product, your username, whether to use proxy, etc.
For the Yoda Speak integration, we want to include the API key and proxy settings, and to allow for insecure requests. We also include a URL parameter, which tells the integration where to send requests. For each parameter, we include a display name that tells the user what the value is used for.
**API key**
Enter the following values for the **apikey** parameter.
* **Parameter name**: apikey
* **Type**: Authentication
* **Mandatory**: unselected
* **Display password**: API Key
For the Yoda Speak integration, the free service does not require an API key and allows up to 60 API calls a day with up to 5 calls an hour. If you require more API calls, FunTranslations offers a paid service that you can access with an API key. In this case, we provide the option for users with a paid subscription to enter their API key, but we don’t make it mandatory. The Authentication parameter type enables using Cortex XSIAM's built-in credential management system to save and use the API key, and ensures that the API key is not displayed to the user and is not stored in logs.
{% hint style="info" %}
### Note
Many integrations that connect to third-party services require an API key for authentication, which is sent with every request to the third party service. Since it’s used by every command that performs an API call, we add it as a global parameter and not an argument.
{% endhint %}
**URL**
Enter the following values for the **url** parameter.
* **Parameter name**: url
* **Type**: Short Text
* **Mandatory**: selected
* **Initial value**:
* **Display name**: API URL
{% hint style="info" %}
### Note
In some cases, the URL parameter may be used for third-party services that enable connecting to more than one server, such as servers in different geographic regions ( or ).
{% endhint %}
**Insecure**
Enter the following values for the **insecure** parameter.
* **Parameter name**: insecure
* **Type**: Boolean
* **Initial value**: false
* **Display name**: Trust any certificate (not secure)
When Trust any certificate is set to true, the integration ignores TLS/SSL certificate validation errors. Use this to test connection issues or connect to a service while ignoring SSL certificate validity. We do not recommend setting this option to true in a production environment.
**Proxy**
Enter the following values for the **proxy** parameter:
* **Parameter name**: proxy
* **Type**: Boolean
* **Initial value**: false
* **Display name**: Use system proxy settings
When Use system proxy settings is set to true, the integration runs using the proxy server (HTTP or HTTPS) defined in the server configuration. In most cases, a proxy is not required.
**Commands settings**
Create commands to be used in the integration code.
1. Click **+Add command**.
2. Enter the following values.
* **Command name**: yoda-speak-translate
* **Description**: Translates a text from English to Yoda
{% hint style="info" %}
### Note
Command names should follow “brand-function” name formatting convention. For example, VirusTotal has a command named `vt-comments-add` that adds a comment to a scan. An exception to this rule is when creating commands that enrich indicators, the commands should be named according to the indicator, for example `!ip` and `!domain`. This naming convention allows commands from multiple integrations to be run together to enrich an indicator. For example, running `!ip ip=8.8.8.8` can trigger multiple integrations that gather information about the IP address. For more information, see [Generic reputation commands](/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/integrations-and-scripts/developing/generic-commands.md#UUID-67e7ba5f-4f74-45fc-8f2f-1aab4ef77100).
{% endhint %}
**Arguments**
Arguments are parameters specific to a command.
In this example, we want to translate English text to Yoda-style text, so we add an argument called `text`. Users can provide a different text string on every call. The argument is mandatory, since the command can’t run if there’s nothing to translate.
**Outputs**
In Cortex XSIAM, the context is a JSON object that is created for each incident and stores results from integration commands and automation scripts. Context is important because it enables you to add information to an incident and run playbooks and integrations utilizing that information.
To write the translation to context, add an output to the `yoda-speak-translate` command.
1. Click **+Add output**.
2. Enter the following values.
* **Context Path**: YodaSpeak.TheForce.Translation
The naming convention for the context path is `Brandname.Object.Property`.
* **Description**: Translation this is
* **Type**: String
---
# 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/integrations-and-scripts/create-a-sample-integration/define-sample-integration-settings.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.