# Software and configuration bundles

Software, firmware, configuration. You can rely on OpenGate to update the software, the firmware, or the configuration files of your remote devices.

The updates can be executed using the operations API, but first of all, OpenGate must know the structure of your update bundles.

The following sections show you how to feed OpenGate with your software, firmware, and configuration files.

## Bundle object structure

A bundle is a group of deployment elements you want to deploy in a remote device. A bundle can contain four file types:

1. SOFTWARE
2. FIRMWARE
3. CONFIGURATION
4. PARAMETERS

See [Bundle Object](#/components/schemas/Bundles)

## Bundle management workflow

```mermaid
flowchart TD
    START(("Start")) --> B["POST bundle"]
    B --> DE["POST deployment element<br>to the bundle"]
    DE --> Q{"Should the bundle have<br>more deployment elements?"}
    Q -- Yes --> DE
    Q -- No --> END(("End"))

    classDef step fill:#addcf8,stroke:#2b7cb8,color:#000
    classDef terminal fill:#a8ecd0,stroke:#2b9c6e,color:#000
    class B,DE step
    class START,END terminal
```

We want to make sure you understand the bundle management workflow, because the update operations will use your bundles.

First of all, you must POST a bundle.

Then you must upload, i.e. POST, as many deployment elements as the bundle should have.

Finally, you must set up the state bundle attribute to `ACTIVE`.

## Deployment element

What is a deployment element? A bundle is formed by deployment elements, each of these elements can have files associated or not, depending on the operation associated with the deployment element. In a bundle, through the deployment elements, you can define different actions that you want to perform in the device, such as installing software, updating it, and more.

The operations allowed for a deployment element are:

1. **Install** - With this operation, you are trying to include a new deployment (of any type) in the device.
2. **Uninstall** - With this operation, you are trying to uninstall a deployment element in the device.
3. **Upgrade** - With this operation, you are trying to change the version of a deployment element.

See the structure of a deployment element object at [Deployment Element](#/components/schemas/Deployment_Element)

## Attach deployment elements 

In order to attach a deployment element to a bundle in the OpenGate API, you must replace `{bundle_name}` and `{version_name}` with the identifiers of the bundle and version you want to attach the deployment element to. Because deployment elements need to be uploaded, this POST request differs from others in the OpenGate API. The request must be encoded according to [RFC 1867, "Form-based File Upload in HTML"](https://tools.ietf.org/html/rfc1867), which OpenGate can parse to "attach" the deployment element to the bundle.

When creating a deployment element, you have three options for attaching a file:

1. **Filling only the `downloadUrl` field**: In this case, the file will be located at the path provided in the `downloadUrl` field.
   
2. **Attaching a file without filling the `downloadUrl` field**: Here, the file is uploaded, and the `downloadUrl` field is automatically populated with the URL of the OpenGate internal file repository.
   
3. **Attaching a file and filling the `downloadUrl` field**: This option combines the previous two; the file is uploaded to the default path, and the device downloads the file from the path specified in the `downloadUrl` field.


{{% notice style="note" title="Important" icon="exclamation-triangle" %}}
You must upload at least one deployment element, or your bundle cannot be activated.
{{% /notice %}}


Additionally, there is an optional parameter called `FileValidationRequired`, which forces the platform to validate the file's integrity. This parameter is only relevant when a valid validator parameter is passed within the accompanying JSON file.

Note that the deployment element file has a maximum size, which can be configured administratively. By default, this limit is set to 22,020,096 bytes.

For the POST request, you must include either the `downloadUrl` parameter, the associated file, or both.


## Comprehensive API actions

### Creating a bundle 

There are two different ways for creating a bundle:

- Step by step creating in the first step the bundle and after that creating the different
deployment elements included in the bundle
- Introducing in the post request a zip file with the complete structure of the bundle.

The zip file will have the next content:
- A file called "manifest.txt" where the content of the bundle is explained
- The files that will become deployment elements within the bundle.

### Updating a bundle

You must replace `{bundle_name}` with the identifier of the bundle you want to update and `{version_name}` with the selected version to be updated.

{{% notice style="info" title="Note" icon="lightbulb" %}}
You cannot update a bundle using the file option available in the create option.
{{% /notice %}}

You cannot update all the fields of a bundle. The following fields are allowed:

- `description`
- `preaction`
- `postaction`
- `userNotes`
- `active`
- Some fields of the `deployments` elements

{{% notice style="note" title="Important" icon="exclamation-triangle" %}}
If a bundle has been used in an update operation, you can only update the following fields:
- `description`
- `userNotes`
- `active`
{{% /notice %}}

Software, firmware, configuration. You can rely on OpenGate to update the software, the firmware, or the configuration files of your remote devices. 

The updates can be executed using the operations API, but first of all, OpenGate must know the structure of your update bundles.  

The following sections show you how to feed OpenGate with your software, firmware, and configuration files.

### Deleting a bundle

{{% notice style="note" title="Important" icon="exclamation-triangle" %}}
If a bundle has been used in an update operation, it can't be deleted.
{{% /notice %}}

## API specification

{{< openapi src="bundle_merged.yaml" >}}