# Bulk Entity Update

## Add a New Bulk Update Schema

This runbook explains how to add new bulk updates to this page:

https://abacus.qaorch.com/contracts/edit/bulk

To add a new bulk update, create a PR in the `frontend-royalties` repository.

Example PR:

https://github.com/theorchard/frontend-royalties/pull/2437/changes

There are several important sections:

### 1. `ACCOUNT_CURRENCY_TABLE_HEADERS` constant

This constant defines the headers for the preview table. These are the columns the user sees before applying the bulk update.

### 2. `AccountCurrencyBulkEditEntry` type

This type is a container for the data that is sent to the backend or displayed in the preview table.

It should include all information required to display the preview and run the update.

### 3. `accountCurrencySchema` constant

This is the main schema definition. It defines the rules for running the bulk update.

### 4. `accountCurrencySchema.expectedFileColumns`

This is the list of columns expected in the CSV file.

The schema is selected based on this list, so the combination of expected columns should be unique across all schemas.

### 5. `accountCurrencySchema.toEntries`

This function maps CSV content to `AccountCurrencyBulkEditEntry` objects.

It typically performs GraphQL `GET` queries to fetch required data, such as the account name used in the preview.

It is strongly recommended to use the `runInBatches` function to avoid sending too many requests to the backend at once.

### 6. `accountCurrencySchema.apply`

This function runs the GraphQL mutation that updates the data.

It has two callback functions: `onSuccess` and `onFail`. Each entry should call one of these callbacks.

If there is already existing graphql mutation, adding new bulk update is easy. Otherwise, it will require a new graphql mutation to be created.

At the moment, there is no dedicated validation mechanism between the `toEntries` and `apply` functions. Because of that, `apply` is the right place to validate each entry.

For example, you can call `onFail` for an entry without an `accountName`, which would indicate that the account was not found.

The `onFail` function receives `error` and `errorMessage` parameters. The `errorMessage` parameter is displayed in the UI. The `error` parameter is not currently used.

After the schema is created, add it to the registry in the `bulk-edit-schema-registry.ts` file.

## Throughout the Process

For risky, important, or new updates, it is recommended to monitor the GraphQL mutations in the browser DevTools.