Create an app with the App Wizard

Use the App Wizard to develop custom security apps to use within playbooks, interface with APIs, or use external services.

The App Wizard is divided into multiple modules, fields, tabs, and files, each representing a logical part of an app. Most of the input elements within the App Wizard have an information icon. On mouse hover, these icons reveal detailed help tips, including naming conventions.

To create an app, complete the following steps:

1. Navigate to the Main Menu.
2. Select Apps.
3. Click App Wizard.

Enter basic app information

Define your app's characteristics by entering information in each of the required fields. The information you enter is used to generate the app's JSON file and fill in the Basic Info section in the app editor later.

1. Enter the basic app information for your app.
2. Click Continue to move to the editing portion of the app wizard.

The required information includes the app name, the app description, product vendor, product name, app publisher, the app's type, and icons in either SVG or PNG format for 's light and dark themes. To learn more about these characteristics see the topic Top level definition.

Any binary files you include in your app, such as the app's icon, are not viewable or editable in the App Wizard's editor.

Example app 'Get IP Info'

This example creates an app that uses the ipinfo.io service. The values given in this table are examples.

Field	Value
App Name	Get IP Info
App Description	This app gets information from the <b>ipinfo.io</b> geolocation service.
Product Vendor	ipinfo.io
Product Name	ipinfo.io
App Publisher	Splunk SOAR App Wizard example
App Type	information
App Logo for light theme	SVG or PNG image file
App Logo for dark theme	SVG or PNG image file

For an expanded list of an app's possible metadata, see Top level definition.

Add any dependencies

You have two options for managing any dependencies for your app, either by using wheel files or else PyPi to install packages. To add dependencies:

1. Click +.
2. Select either wheel or pypi from the dropdown menu.
   • select pypi to install packages, such as numpy, through Python's online package manager.
     • Enter the dependencies module name. You can specify the required version of the module by typing the <$module_name>==<version_number>. If no version is specified, pypi will attempt to install the most recent release available.
       Example: cryptography==41.0.1 This specifies that pypi should be used to install the module cryptography, using version 41.0.1.
   • select wheel to install prepackaged resources through an uploadable file, for use in air-gapped systems or for customized needs.
     • Enter the dependencies module name.
     • Upload the dependencies wheel file. You can drag and drop the file into the space provided, or click the box to browse for the file.
3. Click Confirm.

For more information on specifying dependencies using pip, see Specifying pip dependencies.

Remove a dependency

If you added a dependency previously and have decided to remove it, follow these steps.

To remove a dependency:

1. Expand the Dependency Details section in the left-hand navigation panel.
2. Locate the dependency you wish to remove.
3. Click the trash can icon to delete the dependency.
4. Click Confirm.

Example app 'Get IP Info'

The example app does not have any dependencies.

Enter configuration details

You can use configuration details instead of hardcoded values for asset configuration. This is useful when the values for configuration options could change in some circumstances but you want to be able to control or limit the possible values.

1. Click edit icon.
2. Click Add Configuration Option.
3. Type a name for the configuration option. This name is used in the app's python code, and is not displayed in the user interface. Names should be all lowercase, using underscores to separate words. Do not use spaces or special characters.
4. Select a type for the option
   • string for a sequence of characters
   • boolean for a true or false
   • numeric for integers
   • password for secret identification
   • placeholder to specify the order that the controls are displayed to the user.
5. Add a description of the configuration option. This text is displayed in the user interface next to the configuration option.
6. If the configuration option must be set on the asset, check the box for Required.
7. If you have additional items to set, such as a default value, or you want to provide a list of preset values, click the edit icon in the More field.
   • If you need to set a default value for the asses, type it in the Default field.
   • If you want to provide a drop-down list of values to be used to the asset's configuration, type them in the Value List field.
8. Click Update.
9. To add more configuration options, click Add Configuration Option, and enter the details for that option.
10. When you have added all your configuration options, click Confirm.

See Configuration Section and Place Holder Data Type.

Example app 'Get IP Info'

Set a configuration option for using ipinfo.io.

The app needs to connect to https://ipinfo.io/<ip_to_query> in order to retrieve information about an IP address. The base URL for ipinfo.io, https://ipinfo.io could be hardcoded in the app, but for this example, add it as configuration option.

1. in the left hand navigation panel, in the Configuration Details section, click the edit icon.
2. Click the Add Configuration Option button.
3. Set the following values:

   Field	Value
   Name	base_url
   Data Type	String
   Description	The base URL to connect to retrieve IP information.
   Required	Checked

4. Click More, set the default value to https://ipinfo.io, and click Update.
   Splunk SOAR will display this as the default value for users when they configure a new asset for this app.
5. Click Confirm.

Create app actions

You can select an action for the app to implement based on the type value you select for your app. The types of apps are devops, email, endpoint, identity management, information, network device, network security, reputation, sandbox, siem, ticketing, and virtualization.

If you select the ticketing action, you might see the ingest action "on poll" option. However, the App Wizard doesn't allow ingest actions to be implemented.

1. Click +.
2. Select the type of app you're creating or editing from the App Category drop-down list.
3. Select the action you need from the the Available Actions drop-down list. Some examples follow:
   • lookup ip returns the resolved host name.
   • geolocate ip queries service for IP location information.
   • test connectivity validates the asset configuration for connectivity using supplied configuration.
4. Edit the parameters for the action if needed. For most included actions, you can simply use the parameters provided. For example, for the geolocate ip action all the parameters are usable as is.
5. When you have added the actions for your app, click Save to save your app.

You can also add a custom action if you want to customize your actions' parameters.

1. Click +.
2. Click Switch to Custom Action.
3. Enter values the following fields:

   Field	Value
   Action Name	Name of the action, in lowercase. Names may only contain alphanumeric, spaces, and underscores. Names should follow noun + verb conventions, like "list processes" or "detonate file".
   Description	A very brief description of the action. A more detailed version can be included in the Verbose Description field later.
   Action Type	Select from the menu provided.
   Read Only	Check this box if the action does not change values or states of other items.
   REST Endpoint	The REST API endpoint the action should use in conjunction with a base URL.
   Verbose Description	Enter a more detailed explanation of the action and the expected results.

4. Click Add Parameter to enter any required values for your custom action:

   Field	Value
   Name	The parameter's name.
   Data type	Select a type from the menu.
   Description	This is a description that will be displayed next to the Launch Actiondialog. It is not a name, but a description of the action the user is about to run. Be concise, and avoid long descriptions that will wrap lines.
   Required	If this parameter is required to run the action, this box should be checked.
   Primary	This value is used in conjunction with Contains to display a list of contextual actions. If this parameter is the primary from a range of options available, this box should be checked.
   Contains	Specifies the sort of information the parameter contains. This allows for matching of one action's output parameter to another action's input parameter.

5. Click Confirm.
6. When you have added the actions for your app, click Save to save your app.

See Naming Actions for more information about naming your actions.

Example app 'Get IP Info'

The example app is type information and uses the geolocate ip and lookup ip actions. For this example use the default values.

1. In the left navigation, click the + icon in the Actions section.
2. Select geolocate ip from the Available Actions drop-down menu.
3. Set the REST Endpoint to /geo.
4. Click Confirm.
5. In the left navigation, click the + icon in the Actions section.
6. Select lookup ip from the Available Actions drop-down menu.
7. Set the REST Endpoint to /hostname.
8. Click Confirm.

Edit the test connectivity action.

1. Expand the test connectivity action.
2. Click the Jump to code link.
3. Change the placeholder /endpoint to /region.
4. Click Save.

Add assets

After creating actions and saving your app, you can add assets.

An asset represents a physical or virtual device within your organization such as a server, endpoint, router, or firewall. This is where you define the critical specifics for the asset that your app is interacting with. For example, a password for a Google drive or a Microsoft Exchange token.

If you have not already saved your app, you will be required to save your app as a draft app before you can add assets. Exit the alert and click Save.

From the Console Output and Asset menu bar, complete the following steps:

1. From the Asset drop-down menu, select + New.
2. The Configure New Asset in App Editor dialog opens. There are five sections, Asset Info, Asset Settings, Approval Settings, Access Control, and Tenants.
3. Enter the Asset Info. Some items, such as the product vendor and product name will populate with information from the App Info entered earlier.
   • Asset name
   • Asset description
   • Product vendor
   • Product name
   • Tags
4. Click the Asset Settings tab to modify the asset's settings.
5. Click the right-facing triangle icon to expand the Advanced section:
   • Concurrent action limit to cap the number of actions done at the same time.
   • Select any "just in time" credentials the that will be required to use the asset. These are defined in , and not the App Wizard Editor.
   • Set the user account which will run automated actions.
   • Click + Variable to set any environment variables for holding the specific asset passwords, tokens, or secrets.
6. Click the Approval Settings tab to modify the asset's approval requirements.
   1. Set any primary and secondary approvers, if approval of the app's actions is required.
7. Set any Access Control settings if your organization requires them to perform actions with this asset.
8. Click the Tenants tab to modify the asset's tenant settings, if your organization supports tenants.
9. Set any Tenants settings.
10. Click Save to save your changes.

Remove an asset

If you wish to remove an asset created during development or testing follow these steps.

To remove an asset:

1. From the Home menu, select Apps.
2. Locate your app on one of the tabs, Configured Apps, Unconfigured Apps, or Draft Apps. Apps which have not yet been published are on the Draft Apps tab.
3. Expand the list of configured assets for the app.
4. Locate the asset you want to remove.
5. Click the trash can icon to delete the asset.
6. Click Delete Asset.

Example app 'Get IP Info'

The example app needs an asset to connect to ipinfo.io.

1. In the left navigation, click the right-facing triangle icon to expand the Actions section.
2. In the the Console Output and Asset menu bar, select the asset ipinfo from the Asset drop-down menu.

Test app actions

After creating app actions, you can test the app actions.

1. In the left navigation, click the right-facing triangle icon to expand the Actions section.
2. In the the Console Output and Asset menu bar, select the asset to use for your tests from the Asset drop-down menu.
3. Select the action you wish to test, then click the right-facing triangle icon to expand the action's definition.
4. Type any inputs the action will need to run.
5. Click Test Action.
6. See the results in the Console Output menu.

See Action result.

Jump to code

After creating app actions, you can jump to the code path where the action is defined.

From the action module, click Jump to code. This takes you directly to the component file for the action, _connector.py.

In order for jump to code to work, the function name must follow the convention handle<action_name>. Some apps, such as Maxmind, don't follow this convention, so you can't use jump to code in those scenarios.

If the component file contains errors, you also can't use jump to code in those scenarios.

See App authoring API.

Validate app JSON

A JSON file gets created as you enter your app information, dependencies, configuration details, and actions. Validating the app JSON is optional. You can view it and change it manually if you want to.

To edit the json file, complete the following steps:

1. From App Details, click Edit JSON.
2. Make changes.
3. Click the checkmark to validate the JSON syntax and save the file.

App components

A Splunk SOAR app consists of a number of components. The App Editor displays the component files in the UI. See app components.

Edit your connector module

Splunk SOAR apps provide connectivity between and third-party security products and devices. Connector modules are written in Python and imported into Splunk SOAR as Python modules when packaged within an app.

As you use the App Editor to create configurations, app actions, assets, and so on, these get added to the _connector.py file as stubs. This file acts as a template, so you need to edit it. Editing this file is not optional.

See Connector module development.

Define your constants

Define your constants in the _consts.py file if necessary. For use when you have hardcoded values to be seen by any function. If you define the constants here, then you do not have to find and replace the values throughout the code if the values change.

Provide detailed information about the app

Update the readme.html to provide detailed information for users to read about the app.

Initialize and define a Python package

The _init_.py file is required to initialize and define a Python package. You can use an empty file.

Exclude files from the compiler

The exclude_files.txt is part of the built-in build process. You do not need to edit this file.

Publish your app

When you have completed development of your app, and are ready to use it, you need to publish it. See Publish an app draft.