Almost any business event can be accomplished in BFS with the use of CreateBusinessTransactions via the BFS API. Before using this method it is very important to understand all the implications since it is possible to override the native functionality of BFS through this usage.
We will go more in depth on this topic in future installments of this blog but here we will explore a simple deposit of cash event.
There are two main account worlds in BFS, one is called BFS-accounts and the other is called Custody Accounts. When using BFS with a securities firm or an insurance company as the house it is only the house that should be the owner of any Custody Accounts and the account type is called HouseCustodyAccount in BFS.
The BFS-accounts keep track of the assets that users have in BFS while the Custody Accounts keep track of where the assets are in the outside world. The Custody Accounts should reflect actual holdings that the house has with external institutions.
For this example this means that a deposit made to a customer BFS-account of 100 SEK should also be accompanied by a deposit into a Custody Account like a client asset account held at a bank.
Each asset kept in a BFS-account should be backed up by a matching asset in a Custody Account.
In this example we are going to create a deposit of 100 SEK into an account for our test customer John Doe and we are also going to conduct a deposit into our client assets Custody Account with our bank to reflect that balance.
To work with this method it is also important to understand the structure of the BFS transaction types which will be discussed further in future articles.
Our default transaction types for transferring cash are the following:
| Name | Description |
|---|---|
| Default_Transfer_Trade_Cash | Default means that it is a default transaction type carried by BFS and not a custom transaction type configured by the user Transfer means that it is a transaction of the type Transfer, the three main types of transactions in BFS are Transfer, Trade and Payment. Transfers typically contain only one asset while a Trade usually contains two assets Trade means the balance dimension that will be affected by the transaction, the main balance dimensions in BFS are Trade and Settle Cash means that the transaction type is used for transferring cash and in the BFS transaction mapping files this means that the transaction will only have a configuration for one asset which is called Asset1. If an instrument other than cash is involved it will be Asset2. Also to be explained further in the future. |
| Default_Transfer_Settle_Cash | Default means that it is a default transaction type carried by BFS and not a custom transaction type configured by the user Transfer means that it is a transaction of the type Transfer, the three main types of transactions in BFS are Transfer, Trade and Payment. Transfers typically contain only one asset while a Trade usually contains two assets Settle means the balance dimension that will be affected by the transaction, the main balance dimensions in BFS are Trade and Settle Cash means that the transaction type is used for transferring cash and in the BFS transaction mapping files this means that the transaction will only have a configuration for one asset which is called Asset1. If an instrument other than cash is involved it will be Asset2. Also to be explained further in the future. |
//Create a business event for a deposit with four business transactions using the CreateBusinessTransaction method
var client = new BFSServiceReference.bfsapiSoapClient();
var credentials = new BFSServiceReference.Credentials()
{
UserName = bfsusername, //Username of administrative user in your instance of BFS
Password = bfspassword, //Password of the administrative user in your instance of BFS
};
var response = client.CreateBusinessTransactions(new BFSServiceReference.CreateBusinessTransactionRequest()
{
Credentials = credentials,
identify = bfsidentifier, //Identifier is a unique token for your instance of BFS
Entities = new[]
{
new SuperTransaction()
{
BusinessTransactions = new BusinessTransaction[]
{
//Transaction for customer BFS-account
new BusinessTransaction()
{
Account = new Guid("cbfe4a0d-bf05-4a7e-bdc8-1ee809817bee"),
BusinessTransactionType = "Default_Transfer_Trade_Cash",
TransactionReference = "Test",
Asset1 = new Guid("21b0718c-bce9-4c6b-b1c9-520b65121ff6"),
AmountAsset1 = 100M,
//Since the transaction type is for only the Trade dimension as suggested by the transaction name
TradeDate = DateTime.Parse("2016-04-18")
},
//Transaction for customer BFS-account
new BusinessTransaction()
{
Account = new Guid("cbfe4a0d-bf05-4a7e-bdc8-1ee809817bee"),
BusinessTransactionType = "Default_Transfer_Settle_Cash",
TransactionReference = "Test",
Asset1 = new Guid("21b0718c-bce9-4c6b-b1c9-520b65121ff6"),
AmountAsset1 = 100M,
//Since the transaction type is for only the Settle dimension as suggested by the transaction name
SettlementDate = DateTime.Parse("2016-04-18"),
ValueDate = DateTime.Parse("2016-04-18")
},
//Transaction for house Custody account
new BusinessTransaction()
{
Account = new Guid("25c7b534-c2b6-47a9-a3df-1dcc88b1f49c"),
BusinessTransactionType = "Default_Transfer_Trade_Cash",
TransactionReference = "Test",
Asset1 = new Guid("21b0718c-bce9-4c6b-b1c9-520b65121ff6"),
AmountAsset1 = 100M,
//Since the transaction type is for only the Trade dimension as suggested by the transaction name
TradeDate = DateTime.Parse("2016-04-18")
},
//Transaction for house Custody account
new BusinessTransaction()
{
Account = new Guid("25c7b534-c2b6-47a9-a3df-1dcc88b1f49c"),
BusinessTransactionType = "Default_Transfer_Settle_Cash",
TransactionReference = "Test",
Asset1 = new Guid("21b0718c-bce9-4c6b-b1c9-520b65121ff6"),
AmountAsset1 = 100M,
//Since the transaction type is for only the Settle dimension as suggested by the transaction name
SettlementDate = DateTime.Parse("2016-04-18"),
ValueDate = DateTime.Parse("2016-04-18")
},
},
},
}
});
foreach (var c in response.Entities)
{
Console.WriteLine(c.BrickId + ", " + c.TransactionReference);
}
We have used the Asset ID of SEK and we retrieved the BrickId by using GetCash with the following code as well as the BrickId of the default Custody Account to use:
//Use the GetCash method to retreive information about the asset class cash
var client = new BFSServiceReference.bfsapiSoapClient();
var credentials = new BFSServiceReference.Credentials()
{
UserName = bfsusername, //Username of administrative user in your instance of BFS
Password = bfspassword, //Password of the administrative user in your instance of BFS
};
var cash = client.GetCash(new BFSServiceReference.GetCashRequest()
{
Credentials = credentials,
identify = bfsidentifier, //Identifier is a unique token for your instance of BFS
Args = new GetCashArgs()
{
Keys = new[]
{
"SEK"
}
},
Fields = new BFSServiceReference.GetCashFields()
{
BrickId = true,
Name = true,
Currency = true,
DefaultCustodyAccount = true,
DecimalPlaces = true,
InstrumentStatus = true
},
});
foreach (var c in cash.Result)
{
Console.WriteLine(c.BrickId + ";" + c.Name + ";" + c.Currency + ";" + c.DefaultCustodyAccount + ";" + c.DecimalPlaces);
}
In the GUI we can see the following for the customer:
And for the Custody Account the following is shown:
An external system can use the API-method CreateWithdrawalCashOrder to withdraw money from BFS. This article will also show how to work with transfer receivers (found as External Accounts in BFS).
There are two main ways to work with withdrawals, the first is where we want to withdraws money from a customer account to an external account of that customer. This will result in one transaction taking place at our bank for this specific customer. The second alternative is where a transfer for multiple customers should be made to an external account owned by the house. This could occur if we would like to send money to a fund to cover multiple direct customer purchases or if we have another system that works with insurance products and BFS is being used for managing the trading accounts. In this case a transfer would have to occur to another custody account that is not being monitored by BFS.
When using the second alternative there is a setting available on the external account called batch order. By enabling that setting it is now possible to include multiple individual withdrawal orders in a batch withdrawal order to get one transaction done at the bank.
Once the individual withdrawal orders are batched, which can be accomplished manually or through an automated process in BFS, the batch order number can be used on the bank transfer instruction. Once the external system reads the bank instruction and the reference number it can then request the underlying individual orders via the function GetWithdrawalTransferOrders.
If the batch order number is used as an input to GetWithdrawalTransferOrders the method will return an array of each individual withdrawal order that is included in the batch transaction. By using the External Reference on those individual withdrawal orders the external system will get the reference that it used to create those withdrawal orders in the first place.
We are going to use our test customer, John Doe, to send two withdrawal orders using the external account on the house called Fund A in order to simulate a batch transfer to a fund.
//Create two withdrawals with the WithdrawalCashOrder method
var client = new BFSServiceReference.bfsapiSoapClient();
var credentials = new BFSServiceReference.Credentials()
{
UserName = bfsusername, //Username of administrative user in your instance of BFS
Password = bfspassword, //Password of the administrative user in your instance of BFS
};
var response = client.CreateWithdrawalCashOrders(new BFSServiceReference.CreateWithdrawalCashOrderRequest()
{
Credentials = credentials,
identify = bfsidentifier, //Identifier is a unique token for your instance of BFS
Entities = new[]
{
new WithdrawalCashOrder()
{
AccountNo = "10011484",
IsPercent = false,
Amount = 100,
CurrencyCode = "SEK",
ExternalReference = "Test1",
TransferReceiver = new Guid("026094ef-2da9-4849-9a4c-ab0fe8e53eaf")
},
new WithdrawalCashOrder()
{
AccountNo = "10011484",
IsPercent = false,
Amount = 110,
CurrencyCode = "SEK",
ExternalReference = "Test2",
TransferReceiver = new Guid("026094ef-2da9-4849-9a4c-ab0fe8e53eaf")
}
}
});
foreach (var c in response.Entities)
{
Console.WriteLine(c.BrickId + ", " + c.AccountNo);
}
The result in the console is the following:
We can see in the GUI that two orders were created for the customer:
By clicking on the information icon we can see that the external account used is the one configured on the house called Fund A.
We now have a choice, either we can process these withdrawals individually or we can create a batch order and process them as one transaction since they are both going to the same external account.
For this example we will create a batch order and associate the withdrawals to this. To create a batch order manually we will do the following:
- Navigate to Order Management
- Select Cash Orders
- Click on the Batch Orders tab
Next we will click on create batch orders in the action menu:
The batch order is now created and appears in the list:
The batch order number 70000076 could now be used with GetWithdrawalTransferOrders to collect the underlying orders.
The next step is to send the instruction to the bank, in this article we will do this manually to change the state of the order to Instructed.
Following this we will enter the execution step where we will enter the settlement date, value date and custody account for the withdrawal.
Looking at the custody account the transactions were made as an aggregate amount, in the same way it was booked in the bank, both in the trade and settlement dimension:
In the customer BFS-account the transactions were booked individually:
By using the BFS API it is possible to connect data between several external systems. In this article we will explore how to apply deposit orders of cash and associate these deposits with an allocation profile in BFS.
First we need to create an allocation profile and here we will use GetInstruments to collect the BFS-id's to be used in the Allocation Profile as AllocationItems.
We are going to filter on instrument type 2 which represents funds and we are only going to collect one ISIN which matches a test instrument called Fund A.
//Use the GetInstruments method to get all fund instruments and write their BFS-id's
//in the console
var client = new BFSServiceReference.bfsapiSoapClient();
var credentials = new BFSServiceReference.Credentials()
{
UserName = bfsusername, //Username of administrative user in your instance of BFS
Password = bfspassword, //Password of the administrative user in your instance of BFS
};
var accounts = client.GetInstruments(new BFSServiceReference.GetInstrumentsRequest()
{
Credentials = credentials,
identify = bfsidentifier, //Identifier is a unique token for your instance of BFS
Args = new BFSServiceReference.GetInstrumentsArgs()
{
InstrumentType = 2,
ISINs = new []
{
"SE1234123412"
}
},
Fields = new BFSServiceReference.GetInstrumentsFields()
{
BrickId = true,
Name = true
},
});
foreach (var c in accounts.Result)
{
Console.WriteLine(c.BrickId + ", " + c.Name);
}
The results look like the image below:
Now we are going to create the allocation profile and the code for this example is shown below:
//Create an allocation profile with the CreateAllocationProfiles method
var client = new BFSServiceReference.bfsapiSoapClient();
var credentials = new BFSServiceReference.Credentials()
{
UserName = bfsusername, //Username of administrative user in your instance of BFS
Password = bfspassword, //Password of the administrative user in your instance of BFS
};
var AI1 = new AllocationItem() //The only allocation item
{
Asset = new Guid("138e92a5-f1d6-4473-9ca4-45f511881676"),
AllocationPercentage = 1M
};
var response = client.CreateAllocationProfiles(new BFSServiceReference.CreateAllocationProfileRequest()
{
Credentials = credentials,
identify = bfsidentifier, //Identifier is a unique token for your instance of BFS
Entities = new[]
{
new AllocationProfile()
{
Key = "Alloc1",
Name = "My allocation",
Owner = new Guid("0a39dc30-9e75-4261-920a-1398fb87c952"),
AllocationItems = new []
{
AI1
},
},
}
});
foreach (var c in response.Entities)
{
Console.WriteLine(c.BrickId + "," + c.Errors);
}
The results are the following:
The allocation profile shows up in the GUI according to the image below:
The next step is for the external system to use CreateDepositCashOrder in to send a number of deposits to BFS where the deposits can be associated with Allocation Profiles and then orders to buy the products in the allocation profile will be created.
In the example below we are creating one deposit order to deposit 100 SEK and another order to deposit 110 SEK. We are associating the second deposit with the allocation profile that we created above. All the deposit orders that we are sending to BFS are going to be linked together by a batch order. The BFS-id and the order number of the batch is being returned to the response object and could then be used for the actual bank transfer. When the bank transfer is ready by BFS the reference number can be matched to the batch order and the associated individual deposit orders can be activated and moved to the next state in the workflow.
The flow between the three systems are shown below:
The code for generating the deposits looks like this:
//Create two deposits with the CreateDepositCash method
var client = new BFSServiceReference.bfsapiSoapClient();
var credentials = new BFSServiceReference.Credentials()
{
UserName = bfsusername, //Username of administrative user in your instance of BFS
Password = bfspassword, //Password of the administrative user in your instance of BFS
};
var response = client.CreateDepositCashOrders(new BFSServiceReference.CreateDepositCashOrderRequest()
{
Credentials = credentials,
identify = bfsidentifier, //Identifier is a unique token for your instance of BFS
Entities = new[]
{
new DepositCashOrder()
{
AccountNo = "10032589",
Amount = 100,
CurrencyCode = "SEK",
ExternalReference = "Deposit1"
},
new DepositCashOrder()
{
AccountNo = "10011484",
Amount = 110,
CurrencyCode = "SEK",
ExternalReference = "Test2",
OrderSettlementType = OrderSettlementType.PAYMENT,
AllocationProfileId = new Guid("ea03c9b6-e4f7-4c24-b7cb-1142fcd6faad"),
LinkedAmount = 100M
}
}
});
//Show information about the batch order that was generated
Console.WriteLine(response.batchId + ", " + response.batchOrderNo);
//Show information about the individual deposit orders
Console.WriteLine("Orders:");
foreach (var c in response.Orders)
{
Console.WriteLine(c.OrderId + ", " + c.OrderNo);
}
The results below show the created batch order first and then the individual orders that were created.
The GUI looks like this:
The next step is to process the batch order which would be automatically executed when the matching bank transfer file is imported.
For this article we can do this manually by navigating to the batch order and trigger the next workflow transition.
In the resulting ticket we will write the settlement date, value date and the custody account to use for the deposit.
The custody account now shows the aggregated deposit of 210 SEK while the individual deposits show on the BFS-accounts of the customer:
Customer BFS-account:
