Skip to main content

Contribution Checklist

This document includes a checklist that summarizes the list of files that you need in order to contribute to the Cortex XSOAR content repository.
Before contributing and opening a Pull Request, make sure you meet all the requirements in this checklist.

info

Note that content packs can contain different types of entities, such as integrations, automations (scripts), playbooks, incident-types, incident-fields, etc.

Happy contributing!

Content Pack Checklist#

No matter what you include in your content pack, the pack must include the following:

  • Pack Metadata file (i.e. Packs/YourPackName/pack_metadata.json) : the information about your content pack. It should be compiled with all the required information, as explained here.
  • Pack README (i.e. Packs/YourPackName/README.md): the readme of the pack file. More information here.
  • Release Notes (i.e. Packs/YourPackName/ReleaseNotes/1_0_1.md): these are required only if you are updating an existing Content pack, not for the first. More information here.
note

Use PascalCase (e.g., "PackName") for the names of the pack, its directories, and its entities (integrations, scripts, playbooks, etc.).

As a reference, you can check the tree of the Hello World pack on GitHub.

To create a new content pack directory tree and structure, you should use the demisto-sdk init , as described in the tutorial.

Where do I get all these files?#

Integrations and Scripts should be written with your favorite IDE (see here and here for details on how to set up your dev environment)

All other entity types (Playbooks, Test Playbooks, Incidents/Indicators Fields and Types, Layouts, Classifiers and Mappers, Widgets, Dashboards) should be created in the Cortex XSOAR UI and exported using demisto-sdk download (using the -fmt argument). You can also export the files manually via the Cortex XSOAR UI (either individually using the download icons, or using the Export Custom Content feature under Settings - About - Troubleshooting) but, in that case, you'll need to format them using demisto-sdk format.

Integrations#

If your pack contains an Integration, the integration directory should contain the following:

  • Code file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/YourIntegrationName.py): your integration implementation code.
  • YML file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/YourIntegrationName.yml): YML file with integration metadata.
  • Description file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/YourIntegrationName_description.md): markdown file with instructions on how a customer can configure the integration instance. It shows up as a snippet when the user clicks the question mark icon in the integration configuration panel. More details here.
  • Image file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/YourIntegrationName_image.png): the integration logo.
  • README file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/README.md): the integration documentation, mostly autogenerated (see here).
  • Command examples file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/command_examples): are needed to autogenerate the documentation
  • Unit tests file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/YourIntegrationName_test.py): must be included to automatically test the code during the review phase. More details here. Note: Although we encourage extensive testing, we do not enforce a test to each and every function in the code. We suggest you focus on the important ones and the helper functions.
  • Unit tests data (i.e. Packs/YourPackName/Integrations/YourIntegrationName/test_data/*.json): contain example responses from your product API and are used in Unit tests. Examples from Hello World.
  • Custom Incident Types, Fields, Classifiers, Mappers and Layouts: if your integration has the ability to fetch incidents, most likely you need to provide custom Incident Types and the related entities. This is usually covered during the Design phase: work with your Palo Alto Networks alliance contact if in doubt.

Note: if you use PowerShell and not Python, the extension of the code files will be .ps1 instead of .py.

... and of course your adherence to our best practices and code conventions will be evaluated in a stricter way.

Playbooks#

If your pack contains at least a playbook, the playbook directory must contain the following files:

  • Playbook file (i.e. Packs/YourPackName/Playbooks/playbook-YourPlaybookName.yml): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format.
  • README file (i.e. Packs/YourPackName/Playbooks/playbook-YourPlaybookName_README.md): documentation file for the Playbook, mostly autogenerated
  • Image file (i.e. Packs/YourPackName/doc_files/YourPlaybookName.png): image of the Playbook as exported from the XSOAR UI. Its link should be added to the README file as explained here

Note: the playbook README file must be updated with the correct image link after the Pull Request is opened, as explained in the documentation here

Incident or Indicator Fields#

If your pack contains at least a custom Incident or Indicator field, you'll need:

  • Incident or Indicator field JSON file (i.e. Packs/YourPackName/IncidentFields/YourIncidentFieldName.json or Packs/YourPackName/IndicatorFields/YourIndicatorFieldName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format.
note
  • You will need a single JSON file for each field (individual files are created automatically if you export your content via demisto-sdk download or through the Export Custom Content option under Settings - About - Troubleshooting).
  • It is best practice not to associate a field to all types, but only to the relevant ones (e.g., if you added an incident type, for events fetched from a third-party product, and incident fields to contain details of the event, associate those fields only to that incident type).

Incident or Indicator Types#

If your pack contains at least a custom Incident or Indicator type, you'll need:

  • Incident or Indicator type JSON file (i.e. Packs/YourPackName/IncidentTypes/YourIncidentTypeName.json or Packs/YourPackName/IndicatorType/YourIndicatorTypeName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format.

If you have a custom Incident or Indicator type, most probably you'll also have to include corresponding Classifiers, Mappers and Layouts:

Classifiers and Mappers#

  • Classifier JSON file (i.e. Packs/YourPackName/Classifiers/classifier-YourIntegrationName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format. If exported from Cortex XSOAR 5.x, it must also be converted to 6.0 format.
  • Mapper JSON file (i.e. Packs/YourPackName/Classifiers/classifier-mapper-incoming-YourIntegrationName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format. If exported from Cortex XSOAR 5.x, it must also be converted to 6.0 format.

If you want your pack to be also compatible with version 5.x of Cortex XSOAR (5.0 and 5.5), you'll also need:

  • 5.x Classifier & Mapper JSON file (i.e. Packs/YourPackName/Classifiers/classifier-YourIntegrationName_5_9_9.json)

Incidents or Indicator Layouts#

  • Layout JSON file (i.e. Packs/YourPackName/Layouts/layoutscontainer-YourIncidentTypeName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format. If exported from Cortex XSOAR 5.x, it must also be converted to 6.0 format.

If you want your pack to be also compatible with version 5.x of Cortex XSOAR (5.0 and 5.5), you'll also need:

  • 5.x Layout JSON File (one file for each Layout type, i.e. Packs/YourPackName/Layouts/layouts-details-YourIncidentTypeName.json)

Scripts (Automations)#

If your pack contains at least an automation script, the automation directory should contain the following:

  • Code file (i.e. Packs/YourPackName/YourScriptName/Scripts/YourScriptName.py): your script implementation code.
  • YML file (i.e. Packs/YourPackName/Scripts/YourScriptName/YourScriptName.yml): YML file with script metadata.
  • README file (Packs/YourPackName/Scripts/YourScriptName/README.md): the script documentation, mostly autogenerated (see here).
  • Unit tests file (i.e. Packs/YourPackName/Scripts/YourScriptName/YourScriptName_test.py): must be included to automatically test the code during the review phase. More details here
  • Unit tests data files (i.e. Packs/YourPackName/Scripts/YourScriptName/test_data/*.json): contain example responses from your product API and are used in Unit tests.

Note: if you use PowerShell and not Python, the extension of the code files will be .ps1 instead of .py.

... and of course your adherence to our best practices and code conventions will be evaluated in a stricter way.

Note: if your pack contains both integrations and scripts, you can use a single Test Playbook to test both.

Widgets#

If your pack contains at least a custom widget, you'll need:

  • Widget JSON file (i.e. Packs/YourPackName/Widgets/widget-YourWidgetName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format.

Dashboards#

If your pack contains at least a custom dashboard, you'll need:

  • Dashboard JSON file (i.e. Packs/YourPackName/Dashboard/dashboard-YourDashboardName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format.
note

New contributed content packs, should have all their available content entities supported from Cortex XSOAR version 6.0.0. For example, in a YAML file (integration/script) the version can be set as described here.

Checklist Table#

The requirements above are also summarized in the following table:

Entity TypeAll ContributionsPartner/XSOAR only
Pack
  • Pack metadata
  • Pack README file
  • Release Notes
Design
  • Must follow use case guidelines and review the design document with the Alliances team
Integration
  • Code file
  • YML file
  • Description file
  • Image file
  • README file
  • Command examples file
  • Unit tests file
  • Unit tests data
Playbook
  • Playbook file
  • README file
  • Playbook Image file
Incident/Indicator Field
  • Incident/Indicator field JSON file
Incident/Indicator Type
  • Incident/Indicator type JSON file
Classifier and Mapper
  • Classifier JSON file (for XSOAR 6.0 and above)
  • Mapper JSON file (for XSOAR 6.0 and above)
  • 5.x Classifier JSON file (for XSOAR 5.x)
Incident/Indicator Layout
  • Layout JSON files (for XSOAR 6.0 and above)
  • 5.x Layout JSON file(for XSOAR 5.x)
Script
  • Code file
  • YML file
  • README file
  • Unit tests file
  • Unit tests data
Widget
  • Widget JSON file
Dashboard
  • Dashboard JSON file
Edit this page
Last updated on
Report an Issue