> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch processing

> Processing of multiple requests as part of a batch

In the Bango Platform, entitlements describe a user's ability to access a service provided by a merchant. In some circumstances you might not be able to implement our API methods and want to use an alternative solution to carry out actions on your entitlements.

To support this, Bango Resale includes a batch processing feature that reads and writes files to your own dedicated Amazon S3 bucket. Input files define the actions to take, and output files describe the results.

### Access control

When you sign up to use the Bango Resale API for resellers, Bango Support will supply you with:

* **Amazon S3 endpoint**: you upload all your batch processing data here, and the results appear here after processing
* **Access key**: your unique username for accessing the S3 endpoint
* **Secret key**: your unique password for accessing the S3 endpoint

### Locations

Files related to batch processing are stored at:

```text theme={null}
s3://{customer}/{processing_step}
```

Where:

* *customer* is your unique Amazon S3 bucket
* *processing\_step* is one of:

### Input files

Your batch processing input files, uploaded to the `input` folder of your S3 bucket, must be Windows-1252 encoded and contain [RFC 4180-compliant comma-separated values (CSV)](https://tools.ietf.org/html/rfc4180).

Use the following filename format:

```text theme={null}
{customer}-{action}-{timestamp}.csv
```

Where:

* `customer` is your organization name or a similar reference for your own use
* `action` describes the action or set of actions included in the file – see below. It doesn't need to match any action type names
* `timestamp` is a UTC datetime in the form `YYYYMMDDHHMMSS`

For example, `MyReseller-CANCELLATIONS-20200902120000.csv`.

Each input file must contain a header row, and up to 250 action rows. The header row defines the columns used by every action row.

There are five different types of actions. Four action types use the same columns (and can be included in the same input file or in separate files) and the fifth action type uses a different set of columns (and all actions of this type must be in the same input file, with no other action types). The table shows the actions and their columns:

| Actions | Columns |
| - | - |
| `CANCEL`, `REVOKE`,`SUSPEND`, `RESUME` | `action`, `entitlementId`, `reasonCategory`, `reasonCode`,`reasonDescription` |
| `UPDATE` | `action`, `entitlementId`,`productKey`, `notificationUrl`,`dateExpiry`, `customerIdentifier`, `extensionData` |

Except for `action`, the column names correspond to the fields you would include in the [equivalent API call](/legacy/resale/reseller/api-ref/index). The `action` value is always one of the five action types.

Here are some example input files:

`MyReseller-TERMINATE-20191012112013.csv`

```text theme={null}
action,entitlementId,reasonCategory,reasonCode,reasonDescription
CANCEL,dc48733b-a8a2-475a-8ff1-2dbe6716277e,CUSTOMER_CANCELLED,NOT_RENEWED,Customer has not renewed their entitlement
REVOKE,d12fa153-6bcf-4b0a-b399-158e15d16bff,ACTIVATION_ROLLBACK,FRAUD,Entitlement has been cancelled due to known fraud
```

`MyReseller-SUSPEND-RESUME-20191123170452.csv`

```text theme={null}
action,entitlementId,reasonCategory,reasonCode,reasonDescription
SUSPEND,d7342f06-0382-4bf9-a7f8-eb2bcad07728,ACTIVATION_ROLLBACK,CUSTOMER_PAYMENT_DEFAULT,Customer has defaulted payment.
RESUME,5d5adb03-f803-49d0-b1c8-4ed67e67a2bb,ACTIVATION_RESUMED,CUSTOMER_PAYMENT_RESUMED,Customer has updated payment method.
```

`MyReseller-UPDATE-20191207095617.csv`

```text theme={null}
action,entitlementId,productKey,notificationUrl,dateExpiry,customerIdentifier,extensionData
UPDATE,aa4dc268-f6c9-48a6-a6f1-4de4d021c747,Product2,,,,TestingKey1.TestingValueA;TestingKey2.TestingValueB
```

### File processing

Here's how your input files are processed:

1. The Bango Platform moves each file from the `input` folder to a temporary folder for processing
2. The Bango Platform performs each action in a file, in turn
3. If the action succeeds (HTTP status 2xx), a file is created or updated in `output/success` with the same name as the input file, and a row is added that shows the entitlement record after the action
4. If the action fails (any non-2xx HTTP status), a file is created or updated in `output/error` with the same name as the input file, and a row is added that shows the entitlement record after the action
5. After the Bango Platform has performed all actions in a file, it is moved to the `archive` folder
6. When all processing is complete, the Bango Platform removes all temporary folders

### Output files

The batch processing output files, stored in the `output` folder of your S3 bucket, are Windows-1252 encoded and contain [RFC 4180-compliant comma-separated values (CSV)](https://tools.ietf.org/html/rfc4180).

Every output file includes the action in the first column, and all the fields of the affected entitlement record in the subsequent columns.

Here are some example output files:

`MyReseller-TERMINATE-20191112112013.csv`

```text theme={null}
action,entitlementId,customerIdentifier,productKey,entitlementDisplayName,offerKey,merchantAccountKey,activationCode,dateCreated,dateActivated,dateEnded,dateExpiry,dateFailed,dateSuspended,dateResumed,responseCode,responseMessage,status,extensionData,parameters
CANCEL,dc48733b-a8a2-475a-8ff1-2dbe6716277e,dfb35f4c-5dc4-4eba-b9b2-cfcc22e08d34,Product1,Entitlement1,,BANGO,,2019-10-10T10:21:08Z,2019-10-10T10:21:07Z,2019-10-11T13:31:18Z,2050-02-01T06:00:00Z,0001-01-01T00:00:00Z,,,OK,Success,CANCELLED,"{""CancelReasonCategory"":""CUSTOMER_CANCELLED"",""CancelReasonCode"":""NOT_RENEWED"",""CancelReasonDescription"":""Customer has not renewed their entitlement""}",
REVOKE,d12fa153-6bcf-4b0a-b399-158e15d16bff,c9363a1a-a814-4d6a-96d7-aff90cc757f3,Product1,Entitlement2,,BANGO,,2019-10-10T10:21:08Z,2019-10-10T10:21:07Z,2019-10-11T13:31:18Z,2050-07-19T10:00:00Z,0001-01-01T00:00:00Z,,,OK,Success,REVOKED,"{""CancelReasonCategory"":""ACTIVATION_ROLLBACK"",""CancelReasonCode"":""FRAUD"",""CancelReasonDescription"":""Entitlement has been cancelled due to known fraud""}",
```

`MyReseller-SUSPEND-RESUME-20191123170452.csv`

```text theme={null}
action,entitlementId,customerIdentifier,productKey,entitlementDisplayName,offerKey,merchantAccountKey,activationCode,dateCreated,dateActivated,dateEnded,dateExpiry,dateFailed,dateSuspended,dateResumed,responseCode,responseMessage,status,extensionData,parameters
SUSPEND,d7342f06-0382-4bf9-a7f8-eb2bcad07728,dfb35f4c-5dc4-4eba-b9b2-cfcc22e08d34,Product1,Entitlement1,,BANGO,,2019-10-10T10:21:08Z,2019-10-10T10:21:07Z,0001-01-01T00:00:00Z,2050-02-01T06:00:00Z,0001-01-01T00:00:00Z,2019-11-04T23:08:31Z,,OK,Success,SUSPENDED,,
RESUME,5d5adb03-f803-49d0-b1c8-4ed67e67a2bb,c9363a1a-a814-4d6a-96d7-aff90cc757f3,Product1,Entitlement2,,BANGO,,2019-10-10T10:21:08Z,2019-10-10T10:21:07Z,0001-01-01T00:00:00Z,2050-07-19T10:00:00Z,0001-01-01T00:00:00Z,2019-11-04T23:09:01Z,2019-12-01T05:57:03Z,OK,Success,ACTIVE,,
```

`MyReseller-UPDATE-20191207095617.csv`

```text theme={null}
action,entitlementId,customerIdentifier,productKey,entitlementDisplayName,offerKey,merchantAccountKey,activationCode,dateCreated,dateActivated,dateEnded,dateExpiry,dateFailed,dateSuspended,dateResumed,responseCode,responseMessage,status,extensionData,parameters
UPDATE,aa4dc268-f6c9-48a6-a6f1-4de4d021c747,dfb35f4c-5dc4-4eba-b9b2-cfcc22e08d34,Product2,Entitlement1,,BANGO,,2019-10-10T10:21:08Z,2019-10-10T10:21:07Z,0001-01-01T00:00:00Z,2050-02-01T06:00:00Z,,,OK,Success,ACTIVE,"{""TestingKey1"":""TestingValueA"",""TestingKey2"":""TestingValueB""}",
```

### Coming soon

Support for creating entitlements using batch processing.