# Export Plugins

With the Export custom plugin, you can add your own export format to Ango Hub with only a few clicks.

The Export custom plugin provides a way for you to obtain the normal Ango JSON Export, manipulate it from within a Python script, and present its manipulated version to users for download.

## Creating an Export Plugin

Following the steps outlined [in this section](https://docs.imerit.net/plugins/plugin-developer-documentation/..#creating-a-new-plugin), create a new plugin from the UI, choosing "Export" as the plugin type.

Then, create and run a Python script using the `ExportPlugin` class you can find in our `imerit-ango` Python package under `imerit_ango.plugins`.

In this script, you will get the 'regular' Ango export as input, and you will need to provide a .zip file as well as its name as output. An example is provided below.

You will need to add the `imerit-ango` package to your Python environment by running

```
pip install imerit-ango
```

Here is the class's documentation, and an example:

#### ExportPlugin

Parameters:

* **id:** *str*
  * The plugin's ID. You may obtain this ID from the plugin's information box in the *Development* section of the *Plugin* page.
* **secret:** *str*
  * The plugin's secret. You can think of this as a private key you'll need to be able to connect your script to the plugin. You may obtain this secret from the plugin's information box in the *Development* section of the *Plugin* page.
* **callback:** *Callable\[\[str, dict], Tuple\[str, BytesIO]]*
  * The callback function. This function will be run whenever a user asks for the export using this plugin. More on the callback function below.
* **host:** *str, default="<https://api.ango.ai>"*
  * You do not need to change the host unless you are creating plugins in environments other than our main Cloud instance at hub.ango.ai.

**Callback Function**

Parameters:

* **\*\*data**: *dict*
  * **projectId:** *str*
    * The ID of the project for which the export was wanted.
  * **jsonExport:** *dict*
    * The normal JSON export in Ango Hub Annotation Format. This is the export you would get if you manually requested the export in the "JSON" format.
  * **logger:** *PluginLogger*
    * \[TODO]
  * **apiKey**: *str*
    * The API key of the user running the plugin.
  * **orgId**: *str*
    * The organization ID of the organization where the plugin is run.
  * **runBy**: *str*
    * User ID of the user running the plugin.
  * **session**: *str*
    * ID of the session opened when the plugin is run.
  * **configJSON**: *str*
    * The config JSON your users will pass to you through the *Config JSON* text field when running the plugin. Warning: the JSON will be passed as a string so you will have to destringify it. Example code to obtain the original JSON as a Python object named *config*:

```python
def sample_callback(**data):
    config_str = data.get('configJSON')
    config = json.loads(config_str)
```

Returns:

* export\_response\_obj = `ExportResponse(file=zip_data, file_name=zip_file_name, storage_id="", bucket="")`
  * **zip\_file\_name:** *str*
    * When closing your callback, you'll need to return the name of the export .zip file as a string here.
  * **zip\_data:** *BytesIO*
    * The final .zip you will provide users with, containing the export.

#### Sample Python Script

{% code lineNumbers="true" fullWidth="false" %}

```python
import json
import zipfile
from tqdm import tqdm
from io import BytesIO
from imerit_ango.plugins import ExportPlugin, ExportResponse, run

HOST = '<YOUR HOST>'
PLUGIN_ID = '<YOUR PLUGIN ID>'
PLUGIN_SECRET = '<YOUR PLUGIN SECRET>'


def sample_callback(data):
    # Extract input parameters
    project_id = data.get('projectId')
    json_export = data.get('jsonExport')
    num_assets = data.get('numTasks')
    logger = data.get('logger')
    config_str = data.get('configJSON')
    config = json.loads(config_str)

    logger.info("Plugin session is started!")

    # Check config input
    separator_char = '-'
    if 'separator-character' in config:
        if isinstance(config['separator-character'], str):
            separator_char = config['separator-character']

    # Convert annotation data to intended format
    file_list = []
    for asset_index, asset in enumerate(tqdm(json_export)):
        external_id = asset['externalId']
        data_url = asset['asset']
        objects = asset['task']['tools']

        object_list = []
        for obj in objects:
            if "bounding-box" in obj:
                class_name = obj['title']
                x, y = int(round(obj["bounding-box"]['x'])), int(round(obj["bounding-box"]['y']))
                w, h = int(round(obj["bounding-box"]['width'])), int(round(obj["bounding-box"]['height']))

                single_object_string = ' '.join([class_name, str(x), str(y), str(w), str(h)])
                object_list.append(single_object_string)
        object_string = separator_char.join(object_list)
        file_list.append({'externalId': external_id, 'URL': data_url, 'Annotations': object_string})

    # Create zip file
    zip_file_name = project_id + '.zip'
    zip_data = BytesIO()
    with zipfile.ZipFile(zip_data, mode="w") as zf:
        zf.writestr(project_id + '.json', json.dumps(file_list, indent=4))

    logger.info("Plugin session is ended!")

    export_response_obj = ExportResponse(file=zip_data, file_name=zip_file_name, storage_id="" ,bucket="")
    return export_response_obj


if __name__ == "__main__":
    plugin = ExportPlugin(id=PLUGIN_ID,
                          secret=PLUGIN_SECRET,
                          callback=sample_callback,
                          host=HOST, 
                          version='v3')

    run(plugin, host=HOST)
```

{% endcode %}

For this example, we use the following default Config JSON:

```json
{
  "separator-character": "-"
}
```

## Getting an Export using the Plugin

{% hint style="info" %}
Your Python script needs to be running for users to be able to download exports using your format.
{% endhint %}

Navigate to the project you'd like to get the export of. From the *Settings* tab, enter the *Plugins* section. Click *Open* on the Export plugin of interest.

<figure><img src="https://3895963154-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTcOUG6rfWxqGM0N4db2P%2Fuploads%2FPFLob88tfWWNui1w8mvk%2Fimage.png?alt=media&#x26;token=be7e2307-4266-4a3c-9e28-c4c25ab2d2f1" alt=""><figcaption></figcaption></figure>

From the dialog that pops up, click on *Run*. You will get a notification when your export is ready.