<!--
  This README.md is generated by running:
  "resilient-sdk docgen -p {{ name_underscore }}"

  It is best edited using a Text Editor with a Markdown Previewer. VS Code
  is a good example. Checkout https://guides.github.com/features/mastering-markdown/
  for tips on writing with Markdown

  If you make manual edits and run docgen again, a .bak file will be created

  Store any screenshots in the "doc/screenshots" directory and reference them like:
  ![screenshot: screenshot_1](./screenshots/screenshot_1.png)

  NOTE: If your app is available in the container-format only, there is no need to mention the integration server in this readme.
-->

# {{ display_name }}

## Table of Contents
- [Release Notes](#release-notes)
- [Overview](#overview)
  - [Key Features](#key-features)
- [Requirements](#requirements)
  - [Resilient platform](#resilient-platform)
  - [Cloud Pak for Security](#cloud-pak-for-security)
  - [Proxy Server](#proxy-server)
- [Installation](#installation)
  - [Install](#install)
  - [App Configuration](#app-configuration)
{% if datatables or custom_incident_fields %}
  - [Custom Layouts](#custom-layouts)
{% endif %}
{% for fn in functions %}
- [Function - {{ fn.name }}](#function---{{ fn.anchor }})
{% endfor %}
{% for scp in scripts %}
- [Script - {{ scp.name }}](#script---{{ scp.anchor }})
{% endfor %}
{% for dt in datatables %}
- [Data Table - {{ dt.name }}](#data-table---{{ dt.anchor }})
{% endfor %}
{% if custom_fields %}
- [Custom Fields](#custom-fields)
{% endif %}
{% if custom_artifact_types %}
- [Custom Artifact Types](#custom-artifact-types)
{% endif %}
{% if rules %}
- [Rules](#rules)
{% endif %}
- [Troubleshooting & Support](#troubleshooting--support)
---

## Release Notes
<!--
  Specify all changes in this release. Do not remove the release 
  notes of a previous release
-->
| Version | Date | Notes |
| ------- | ---- | ----- |
| 1.0.0 | MM/YYYY | Initial Release |

---

## Overview
<!--
  Provide a high-level description of the function itself and its remote software or application.
  The text below is parsed from the "description" and "long_description" attributes in the setup.py file
-->
**{{ short_description }}**

 ![screenshot: main](./doc/screenshots/main.png)

{{ long_description }}

### Key Features
<!--
  List the Key Features of the Integration
-->
* Key Feature 1
* Key Feature 2
* Key Feature 3

---

## Requirements
<!--
  List any Requirements 
-->
This app supports the IBM Resilient SOAR Platform and the IBM Cloud Pak for Security.

### Resilient platform
The Resilient platform supports two app deployment mechanisms, App Host and integration server.

If deploying to a Resilient platform with an App Host, the requirements are:
* Resilient platform >= `{{ server_version }}`.
* The app is in a container-based format (available from the AppExchange as a `zip` file).

If deploying to a Resilient platform with an integration server, the requirements are:
* Resilient platform >= `{{ server_version }}`.
* The app is in the older integration format (available from the AppExchange as a `zip` file which contains a `tar.gz` file).
* Integration server is running `{{ res_circuits_dependency_str }}`.
* If using an API key account, make sure the account provides the following minimum permissions: 
  | Name | Permissions |
  | ---- | ----------- |
  | Org Data | Read |
  | Function | Read |

The following Resilient platform guides provide additional information: 
* _App Host Deployment Guide_: provides installation, configuration, and troubleshooting information, including proxy server settings. 
* _Integration Server Guide_: provides installation, configuration, and troubleshooting information, including proxy server settings.
* _System Administrator Guide_: provides the procedure to install, configure and deploy apps. 

The above guides are available on the IBM Knowledge Center at [ibm.biz/resilient-docs](https://ibm.biz/resilient-docs). On this web page, select your Resilient platform version. On the follow-on page, you can find the _App Host Deployment Guide_ or _Integration Server Guide_ by expanding **Resilient Apps** in the Table of Contents pane. The System Administrator Guide is available by expanding **System Administrator**.

### Cloud Pak for Security
If you are deploying to IBM Cloud Pak for Security, the requirements are:
* IBM Cloud Pak for Security >= 1.4.
* Cloud Pak is configured with an App Host.
* The app is in a container-based format (available from the AppExchange as a `zip` file).

The following Cloud Pak guides provide additional information: 
* _App Host Deployment Guide_: provides installation, configuration, and troubleshooting information, including proxy server settings. From the Table of Contents, select Case Management and Orchestration & Automation > **Orchestration and Automation Apps**.
* _System Administrator Guide_: provides information to install, configure, and deploy apps. From the IBM Cloud Pak for Security Knowledge Center table of contents, select Case Management and Orchestration & Automation > **System administrator**.

These guides are available on the IBM Knowledge Center at [ibm.biz/cp4s-docs](https://ibm.biz/cp4s-docs). From this web page, select your IBM Cloud Pak for Security version. From the version-specific Knowledge Center page, select Case Management and Orchestration & Automation.

### Proxy Server
The app **does/does not** support a proxy server.

---

## Installation

### Install
* To install or uninstall an App or Integration on the _Resilient platform_, see the documentation at [ibm.biz/resilient-docs](https://ibm.biz/resilient-docs).
* To install or uninstall an App on _IBM Cloud Pak for Security_, see the documentation at [ibm.biz/cp4s-docs](https://ibm.biz/cp4s-docs) and follow the instructions above to navigate to Orchestration and Automation.

### App Configuration
The following table provides the settings you need to configure the app. These settings are made in the app.config file. See the documentation discussed in the Requirements section for the procedure.

| Config | Required | Example | Description |
| ------ | :------: | ------- | ----------- |
{% for app_config in app_configs %}
| **{{ app_config.name }}** | Yes | `{{ app_config.placeholder }}` | *Enter a description of the config here.* |
{% endfor %}

{% if datatables or custom_incident_fields %}
### Custom Layouts
<!--
  Use this section to provide guidance on where the user should add any custom fields and data tables.
  You may wish to recommend a new incident tab.
  You should save a screenshot "custom_layouts.png" in the doc/screenshots directory and reference it here
-->
* Import the Data Tables and Custom Fields like the screenshot below:

  ![screenshot: custom_layouts](./doc/screenshots/custom_layouts.png)

{% endif %}

---

{% for fn in functions %}
## Function - {{ fn.name }}
{{ fn.description }}

 ![screenshot: fn-{{ fn.simple_name }} ](./doc/screenshots/fn-{{ fn.simple_name }}.png)

<details><summary>Inputs:</summary>
<p>

| Name | Type | Required | Example | Tooltip |
| ---- | :--: | :------: | ------- | ------- |
{% for fn_input in fn.inputs %}
| `{{ fn_input.name }}` | `{{ fn_input.type }}` | {{ fn_input.required }} | `{{ fn_input.placeholder }}` | {{ fn_input.tooltip }} |
{% endfor %}

</p>
</details>

<details><summary>Outputs:</summary>
<p>

```python
results = {
    # TODO: Copy and paste an example of the Function Output within this code block.
    # To view the output of a Function, run resilient-circuits in DEBUG mode and invoke the Function. 
    # The Function results will be printed in the logs: "resilient-circuits run --loglevel=DEBUG"
}
```

</p>
</details>

<details><summary>Example Pre-Process Script:</summary>
<p>

```python
{{ fn.pre_processing_script }}
```

</p>
</details>

<details><summary>Example Post-Process Script:</summary>
<p>

```python
{{ fn.post_processing_script }}
```

</p>
</details>

---
{% endfor %}

{% for scp in scripts %}
## Script - {{ scp.name }}
{{ scp.description }}

**Object:** {{ scp.object_type }}

<details><summary>Script Text:</summary>
<p>

```python
{{ scp.script_text }}
```

</p>
</details>

---
{% endfor %}

{% for dt in datatables %}
## Data Table - {{ dt.name }}

 ![screenshot: dt-{{ dt.simple_name }}](./doc/screenshots/dt-{{ dt.simple_name }}.png)

#### API Name:
{{ dt.api_name }}

#### Columns:
| Column Name | API Access Name | Type | Tooltip |
| ----------- | --------------- | ---- | ------- |
{% for col in dt.columns %}
| {{ col.name }} | `{{ col.api_name }}` | `{{ col.type }}` | {{ col.tooltip }} |
{% endfor %}

---
{% endfor %}

{% if custom_fields %}
## Custom Fields
| Label | API Access Name | Type | Prefix | Placeholder | Tooltip |
| ----- | --------------- | ---- | ------ | ----------- | ------- |
{% for f in custom_fields %}
| {{ f.label }} | `{{ f.api_name }}` | `{{ f.type }}` | `{{ f.prefix }}` | {{ f.placeholder }} | {{ f.tooltip }} |
{% endfor %}

---
{% endif %}

{% if custom_artifact_types %}
## Custom Artifact Types
| Display Name | API Access Name | Description |
| ------------ | --------------- | ----------- |
{% for a in custom_artifact_types %}
| {{ a.display_name }} | `{{ a.api_name }}` | {{ a.description }} |
{% endfor %}

---
{% endif %}

{% if rules %}
## Rules
| Rule Name | Object | Workflow Triggered |
| --------- | ------ | ------------------ |
{% for rule in rules %}
| {{ rule.name }} | {{ rule.object_type }} | `{{ rule.workflow_triggered }}` |
{% endfor %}

---
{% endif %}

## Troubleshooting & Support
Refer to the documentation listed in the Requirements section for troubleshooting information.

### For Support
{% if supported_app %}
This is an IBM supported app. Please search https://ibm.com/mysupport for assistance.
{% else %}
This is a IBM Community provided App. Please search the Community https://ibm.biz/resilientcommunity for assistance.
{% endif %}
