Batch processing

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:

s3://{customer}/{processing_step}

Where:

• customer is your unique Amazon S3 bucket
• processing_step is one of:
• input: where you place your files to process
• archive: where the Bango Platform moves files from input after processing is complete
• output/success: where the Bango Platform puts output files for successful actions
• output/error: where the Bango Platform puts output files for failed actions

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).

Use the following filename format:

{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:

Except for action, the column names correspond to the fields you would include in the equivalent API call. The action value is always one of the five action types.

Here are some example input files:

MyReseller-TERMINATE-20191012112013.csv

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

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

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
• 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
• 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
3. After the Bango Platform has performed all actions in a file, it is moved to the archive folder
4. 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).

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

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

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

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.