7 - Validate Transaction Dates

Last updated 18/12/2023

This documentation is to demonstrate how we can use metadata provided in the Buy field to validate the purchase of shares to a specific date.

When in Five's Code Editor you will be interacting with Five's API. In the

CheckBuyQuantity()

function you will be using the following functions and properties:

form.<formID>.<fieldID>

- is a property used on the

Five

object that returns the value associated to the combination of the form ID and the field ID for the form in the stack.

createError()

- is a function used on the

Five

object that returns an error with an optional message and notification parameters.

getMetadata()

- is a function used on the

Five

object that provides metadata from a field.

success()

- is a function used on the

Five

object that returns a

FiveError

indicating success.

Navigate to the Code Editor

1. Click Logic in the menu.

2. Click Code Editor in the sub-menu.

Figure 1 - Code Editor menu item

Add the CheckBuyQuantity Function

1. Click the Add New Code Button.

Figure 2 - Add New Code button

2. Type CheckBuyQuantity in the Function ID field.

3. Click the lookup icon in the Language field and select TypeScript.

4. Click the OKAY button

Figure 3 - Add the CheckBuyQuantity function

5. Click the Copy button on the below code block.

CheckBuyQuantity

function CheckBuyQuantity(five: Five, context: any, result: FiveError) : FiveError {
    const qty: number = parseInt(five.field.Quantity);
    if (qty > five.form.Sells.Quantity) {
        return five.createError(result, 'Stock quantity exceeds quantity in this sale');
    }

    if (qty > five.getMetadata('Allocations', 'BuyKey', 'Holding')) {
        return five.createError(result, 'Stock quantity exceeds remaining stock in this buy');
    }

    return five.success(result, '');
}

6. Paste the code block over the template in the Code Editor.

7. Click the Save Current Tab button.

Figure 4 - Save Current Tab button

Navigate to Forms

info

The CheckBuyQuantity function needs to be attached to the Quantity field on the Allocations form. The function can then use the metadata provided in the Buy field to know the quantity of stock for each date.

1. Click Visual in the menu.

2. Click Forms in the sub-menu.

Figure 5 - Forms menu item

Attach the CheckBuyQuantity Function

Path: Allocations form > General page > Quantity field > On Validate event

1. Select the Allocations record in the list.

2. Click the Pages tab.

Figure 6 - Pages tab

3. Select the General record.

Figure 7 - General record

4. Click the Fields tab.

Figure 8 - Fields tab

5. Select the Quantity record.

Figure 9 - Quantity record

6. Click the Events tab.

Figure 10 - Events tab

7. Either click the Edit button in the form app bar, or click directly in the On Validate field.

8. Click the lookup icon in the On Validate field and select CheckBuyQuantity.

Figure 11 - On Validate field

9. Click the Save button in the form app bar.

Figure 12 - Save button

10. Click the Save button in the form app bar above the list.

Figure 13 - Save button

Run the Portfolio Application

tip

This is a good time to run the Portfolio application and see how the CheckBuyQuantity function works!

1. Click the Run button in Five's toolbar.

Figure 14 - Run button

2. Select the Growth Portfolio record.

3. Click the Down button in the form app bar.

Figure 15 - Down button

Test the CheckBuyQuantity Function

1. Select Sells in the menu.

2. Click the Add Item button.

3. Click the lookup icon in the Stock field and select NAB.

4. Click the calendar icon in the Transaction Date field, select the current date, and click the OK button.

5. Type 1100 in the Quantity field.

6. Type 1.00 in the Price field.

7. Type 10.00 in the Fees field, press tab.

Figure 16 - Add a NAB sell transaction

8. Click the Add Allocations button.

Figure 17 - Add Allocations button

9. Click the lookup icon in the Buy field and select 2023-12-13.

10. Type 1100 in the Quantity field, press tab.

Figure 18 - Stock quantity error

info

An error is returned letting us know that the Stock quantity exceeds remaining stock for this buy. This is because even though we have a total of 1200 NAB shares, we only purchased 1000 NAB shares on the transaction date 2023-12-13.

12. Click the OK button.

Figure 19 - OK button

13. Type 1000 in the Quantity field.

14. Click the Save button in the form app bar.

Figure 20 - Add an allocation

Problem

If you take a look at the image below, we would be able to save the Sell record at this point as we have 1000 NAB shares purchased on the 2023-12-13. If we were to click the Save button on the Sells form, the sale would be submitted even though the values in the Quantity fields for both forms do not equal. In Five, we can create a server-side function to ensure the values in the Quantity fields match on the Sells and Allocations forms to ensure the integrity of the data.

Figure 21 - Quantity fields don't equal

15. Click the Cancel button in the form app bar.

Figure 22 - Cancel button

16. Close the browser tab and return to Five.