General Ledger for Multi-Tenancy

The General Ledger (GL) utilities support multi-tenancy by processing and posting events in specific tenant instances of the Event Repository. If you are not using multi-tenancy, the GL utilities process and post events in the base Event Repository.

Multi-tenant installations of MATRIXX use the same GL utilities as base installations (gl_processor.yaml and gl_posting.yaml) but with an added tenantID argument. For example, in processing:

gl_processor glDate(yyyy-mm-dd) gl_processor.yaml [tenantId]
gl_processor -p password gl_processor.yaml [tenantId]

For example, in posting:

gl_posting [-noaggr] startDate(yyyy-mm-dd) endDate(yyyy-mm-dd) outputFolder outputFilePrefix gl_posting.yaml [tenantId]
gl_posting -p password gl_posting.yaml [tenantId]

The following gl_processor.yaml file has information about how to process events in the Event Repository:

# MongoDB user id
dbUserId: MtxApp
 
# encrypted password
dbPassword: 12345678
 
# MongoDB server address
dbServerAddress: localhost:27017
#dbServerAddress: cluster0.abcde.mongodb.net
 
#specify whether the value of the dbServerAddress key corresponds to a DNS SRV record
#if isDNSSeedList is "yes", then the connection string will have the "mongodb+srv://" prefix.
isDNSSeedList: "no"
 
# whether to blend unrecognized revenue from purchases of the the same asset (default value is yes)
blendUnrecognizedRevenue: "yes"
 
# precision of currency balance (default value is 2)
currencyPrecision: 2
 
# decimal precision to be used during divide operations (default value is 12)
decimalPrecision: 12
 
# number of threads to use (default value is 16)
numberOfThreads: 16
 
# precision of external GL reporting systems (default value is currencyPrecision)
postingPrecision: 2
 
# additional fields to copy into GL journal entries
# copyEventFields: InitiatorExternalId,EventId
 
tenants:
- id: Foo
  dbUserId: MtxAppFoo
  dbPassword: 12345678
  dbServerAddress: localhost:27017
  eventDBName: MtxEventDatabaseFoo
  isDNSSeedList: "no"
  blendUnrecognizedRevenue: "yes"
  currencyPrecision: 2
  decimalPrecision: 12
  numberOfThreads: 16
  postingPrecision: 2
# copyEventFields: InitiatorExternalId,EventId
- id: Bar
  dbUserId: MtxAppBar
  dbPassword: 12345678
  dbServerAddress: localhost:27017
  eventDBName: MtxEventDatabaseBar
  isDNSSeedList: "no"
  blendUnrecognizedRevenue: "yes"
  currencyPrecision: 2
  decimalPrecision: 12
  numberOfThreads: 16
  postingPrecision: 2
# copyEventFields: InitiatorExternalId,EventId

The tenants array includes tenant-specific configuration keys:

id — The string ID of the tenant.
eventDBName — The name of the MongoDB database used to store the tenant's events.

If a key is not specified in the tenants array, the value from the global level is used.

When the GL Processor utility is executed to process events in the base Event Repository, the existing keys at the global level (outside of the tenants array) are used.

The following gl_posting.yaml file has key values for each tenant GL database to generate reports from:

# MongoDB user id
dbUserId: MtxApp
 
# encrypted password
dbPassword: 12345678
 
# MongoDB server address
dbServerAddress: localhost:27017
#dbServerAddress: cluster0.abced.mongodb.net
 
#specify whether the value of the dbServerAddress key corresponds to a DNS SRV record
#if isDNSSeedList is "yes", then the connection string will have the "mongodb+srv://" prefix.
isDNSSeedList: "no"
 
# Fields to group when the posting amount is to be aggregated
aggregateByFields: Account1,Account2,TxnType,GlCenter
 
# Fields to be included in the posting when aggregation is not required
exportFields: Account1,Account2,TxnType,GlCenter,Amount
 
# Number of entries per posting file (default=1000)
numEntryPerFile: 1000
 
tenants:
- id: Foo
  dbUserId: MtxAppFoo
  dbPassword: 12345678
  dbServerAddress: localhost:27017
  isDNSSeedList: "no"
  aggregateByFields: Account1,Account2,TxnType,GlCenter
  exportFields: Account1,Account2,TxnType,GlCenter,Amount
  numEntryPerFile: 1000
- id: Bar
  dbUserId: MtxAppBar
  dbPassword: 12345678
  dbServerAddress: localhost:27017
  isDNSSeedList: "no"
  aggregateByFields: Account1,Account2,TxnType,GlCenter
  exportFields: Account1,Account2,TxnType,GlCenter,Amount
  numEntryPerFile: 1000

The tenants array includes tenant-specific configuration keys. If a key is not specified in the tenants array, the value from the global level is used.

When the GL Posting utility is executed to generate reports from the GL database associated with the base Event Repository, the existing keys at the beginning of the YAML file (outside of the tenants array) are used.

Tenant Configuration

When a new tenant is added to the MATRIXX platform, a MongoDB database is created to store the new tenant's events and another MongoDB database is created to store GL data for the new tenant. The same configuration steps required for the base Event Repository (collections, indexes, user ID, and so on) and the MongoDB GL database must be performed for the tenant's Event Repository and GL database. Finally, the gl_processor.yaml and gl_posting.yaml files used to run the GL utilities must be updated with the tenant configuration.

The name of the MongoDB GL database for a tenant with a xxx ID is MtxGlDatabasexxx. There is no restriction on the database name for the tenant Event Repository, but the tenant GL database name must be MtxGlDatabasexxx. The name of the base Event Repository is MtxEventDatabase and the name of the base GL database is MtxGlDatabase.

On the MongoDB instance used for the new tenant:

Create a MongoDB user to be used for running the GL utilities for the new tenant.
Assign the following roles to the new user:
- read role to the tenant's Event Repository.
- readWrite to the tenant's GL database.
Add an index keyed on GlDate, WalletOwnerId, and EventType to the event collections in the tenant's Event Repository.
Add an index keyed on GlDate and WalletOwnerId to the GlCollection collection in the tenant's GL database.
Add a TTL index keyed on GlDate to the GlCollection collection in the tenant's GL database.

Edit the gl_processor.yaml file (located in /sync/conf).

Enter the new tenant's information – ID, MongoDB user ID, MongoDB server address, name of Event Repository, and GL configuration.

Run the following to encrypt the password and save it:

java -jar gl_processor.jar -p password gl_processor.yaml tenantId

Edit the gl_posting.yaml file (located in /sync/conf).

Enter information of the new tenant – ID, MongoDB user ID, MongoDB server address, and GL configuration.

Run the following to encrypt the password and save it:

java -jar gl_posting.jar -p password gl_posting.yaml tenantId

Scheduled Jobs and Recovery

After events for a tenant and a GL date are loaded to the Event Repository, the GL Processor utility can be executed for the tenant and GL date.

Multiple jobs could be scheduled to perform GL processing for various tenants in sequential or parallel order. During system recovery when there are missing MATRIXX Event File (MEF) files whose Event Detail Records (EDRs) are not loaded to the Event Repository, GL processing for one or more tenants might need to be restarted because a MEF file could contain EDRs for one or more tenants.