Investran

Front-to-Back-Office Software Suite for Private Equity Investing

Investran 6.2 SR3 Developer's Guide to Active Template Manager

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Copyright Notice
Copyright 2011 by SunGard Investran. This document and the software described within are copyrighted with all rights reserved. No part of this document may be reproduced, transcribed, transmitted, stored in an electronic retrieval system, or translated into any language in any form by any means without prior written permission of SunGard. SunGard makes no warranties, express or implied, in this document. In no event shall SunGard be liable for damages of any kind arising out of the use of this document or the information contained within.

Trademarks
SunGard, the SunGard logo, Investran Accounting, Investran CRM, and SunGard DX are trademarks or registered trademarks of SunGard Data Systems, Inc. or its subsidiaries in the U.S. and other countries. All other trade names are trademarks or registered trademarks of their respective holders.

Confidentiality Statement
This document contains information that is confidential or proprietary to SunGard (or its direct or indirect subsidiaries). By accepting this document, you agree that: (1) if there is any pre-existing contract containing disclosure and use restrictions between your company and SunGard, you and your company will use this information in reliance on and submit to the terms of any such pre-existing context; or (2) if there is no contractual relationship between you or your company and SunGard, you and your Company agree to protect this information and not reproduce, disclose or use the information in any way, except as may be required by law.

Disclaimer
The screens and illustrations are representative of those created by the software, and are not always exact copies of what appears on the computer monitor. Companies, names and data used in examples herein are fictitious unless otherwise noted. The material in this document is for information only, and is subject to change without notice. SunGard reserves the right to make changes in the product design and installation software without reservation and without notice to users.

Applicability
This guide applies to Investran 6.2 SR3. Document last updated on 6/6/11.

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Table of Contents
1. INTRODUCTION ....................................................................................................................................................................................................................... 1 DEFINITIONS, ACRONYMS, ABBREVIATIONS ................................................................................................................................................................................ 1 2. GETTING STARTED IN ATM................................................................................................................................................................................................ 3 LAUNCHING ATM........................................................................................................................................................................................................................... 3 MENU OPTIONS ............................................................................................................................................................................................................................... 4 System Menu .......................................................................................................................................................................................................................... 4 Process Maintenance Sub-Menu (Under System Menu)..................................................................................................................................................... 4 Active Template Menu .......................................................................................................................................................................................................... 4 Journal Entry Menu................................................................................................................................................................................................................ 5 Transaction Template Menu .................................................................................................................................................................................................. 5 Parameters Menu.................................................................................................................................................................................................................... 5 Driver Reports Menu ............................................................................................................................................................................................................. 6 Auxiliary Reports Menu ........................................................................................................................................................................................................ 6 VBA Code Menu.................................................................................................................................................................................................................... 6 ACTIVE TEMPLATE ATTRIBUTES ................................................................................................................................................................................................... 7 Add/Edit Active Template Panel .......................................................................................................................................................................................... 7 NAVIGATION ................................................................................................................................................................................................................................... 9 Database Connection ............................................................................................................................................................................................................. 9 Active Templates .................................................................................................................................................................................................................10 Parameters ............................................................................................................................................................................................................................11 Driver Reports ......................................................................................................................................................................................................................12 Auxiliary Reports .................................................................................................................................................................................................................13 Journal Entries ......................................................................................................................................................................................................................14 Transaction Templates .........................................................................................................................................................................................................15 Visual Basic for Applications (VBA) .................................................................................................................................................................................16 3. CLASSES COMMONLY USED IN VBA .............................................................................................................................................................................19 THE APPLICATION.........................................................................................................................................................................................................................19 Public Class Definition ........................................................................................................................................................................................................19 Properties ..............................................................................................................................................................................................................................20 Methods ................................................................................................................................................................................................................................20 Events....................................................................................................................................................................................................................................20 THE CONTEXT ...............................................................................................................................................................................................................................21 Public Class Definition ........................................................................................................................................................................................................22 Properties ..............................................................................................................................................................................................................................22 RWREPORT CLASS .......................................................................................................................................................................................................................28 Public Class Definition ........................................................................................................................................................................................................29 Properties ..............................................................................................................................................................................................................................29 Methods ................................................................................................................................................................................................................................30 Example ................................................................................................................................................................................................................................30 INVESTORSET CLASS ....................................................................................................................................................................................................................31 Public Class Definition ........................................................................................................................................................................................................31 Properties ..............................................................................................................................................................................................................................31 Methods ................................................................................................................................................................................................................................33 Example ................................................................................................................................................................................................................................34 4. ACTIVE TEMPLATE EXAMPLES .....................................................................................................................................................................................35 ACTIVE TEMPLATE WITH NO DRIVER REPORT ...........................................................................................................................................................................35 Create the Active Template and Assign Attributes............................................................................................................................................................36 Define the Journal Entry/Transaction Templates...............................................................................................................................................................37

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Define the AT Parameters ...................................................................................................................................................................................................39 Add VBA Code ....................................................................................................................................................................................................................41 Auxiliary Reports .................................................................................................................................................................................................................45 ACTIVE TEMPLATE WITH DRIVER REPORT .................................................................................................................................................................................46 Create AT and Set Attributes ..............................................................................................................................................................................................47 Define Journal Entries/Transactions ...................................................................................................................................................................................47 Define Parameters ................................................................................................................................................................................................................48 Define and Configure the Driver Report ............................................................................................................................................................................48 Add VBA Code ....................................................................................................................................................................................................................49 5. ACTIVE TEMPLATE DEVELOPMENT ............................................................................................................................................................................. 52 ACTIVE TEMPLATE DEVELOPMENT TIPS.....................................................................................................................................................................................52 6. DEBUGGING ACTIVE TEMPLATES ................................................................................................................................................................................54 VBA SOURCE DEBUGGING .......................................................................................................................................................................................................... 54 DEBUG LOG ...................................................................................................................................................................................................................................59 7. EXECUTING ACTIVE TEMPLATES .................................................................................................................................................................................60 REQUIRED CONDITIONS................................................................................................................................................................................................................60 EXECUTING THE ACTIVE TEMPLATE ...........................................................................................................................................................................................61 AT EXECUTION MAINTENANCE ...................................................................................................................................................................................................64 8. APPENDIX A: ATM PROPERTIES .....................................................................................................................................................................................68 APPENDIX B: TROUBLESHOOTING.....................................................................................................................................................................................72

ii

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Chapter

1
1. Introduction
The Accounting module provides the means to manually create batches in Investran. The use of current Investran functionality such as templates, transaction types, and system Active Templates aids in recording the journal entries for these transactions. Often, however, these transactions represent complex business scenarios, requiring the development and use of detailed spreadsheets to record the proper journal entries. The Active Template Manager (ATM) application facilitates the recording of transaction batches by giving the Investran user a flexible and user-driven method to create transaction batches in an automated way. The ATM is one of the tools available in the Investran suite of applications. It provides a framework in which custom Active Templates may be developed. ATM functionality may be used to create batches, only. ATM may not be used to either edit or modify existing batches. The more complex business transactions will usually require ATM to utilize basic programming through Visual Basic for Applications (VBA). This guide assumes the reader is familiar with Investran concepts as well as Report Wizard.

Definitions, Acronyms, Abbreviations

The following list highlights some of the primary terms and abbreviations that will be used throughout this document. AT Active Template. The software unit that results from this development process: consisting of a collection of reports, parameters, transaction templates, and/or VBA, which can be executed by the ATM Engine to create transaction batches. ATM - Active Template Manager. The Investran development tool for creating, debugging, and testing Active Templates. ATM Engine The run-time engine which executes on the application server and creates batches from valid Active Templates. AT Execution The ATM Engine process that executes a 'well-defined' Active Template according to the definitions, properties, parameters, driver and auxiliary reports, and VBA code associated with the AT object. A successful AT Execution will generate the Active Template's transaction batches, which will reside in the temporary results Staging table, awaiting transfer to Investran.

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Allocation Rule (AR) The method used to allocate the total amount of a transaction, to each of the individual investors of the specified Legal Entity. Allocation rules can be either static or dynamic, system or user-defined. For more information on creating user-defined dynamic Allocation Rules, see the Developers Guide to Allocation Rules Manager. Transaction Type - An identifier to any debit or credit of a journal entry. For example, a 'Purchase' transaction type is a debit to the Investment G/L account. A 'Return of Capital' transaction type is a credit to the Investment G/L account. Map to a Property - An attribute of an Active Template parameter or driver report column, whereby the parameter or column is mapped to a transaction property. At run time for the Active Template, the property value mapped to the parameter will override any context property values. Driver Reports - Report Wizard reports that map columns to the property values that are required to execute a specific Active Template, at the appropriate hierarchical level. The number of rows retrieved by the driver report ultimately determines the number of transactions that will be created by the Active Template. Driver reports can range in number from zero to a maximum of three. When no Driver report exists for an Active Template, the required property values will be hard coded into the Active Template. Auxiliary Reports - Report Wizard reports that define the additional data items required to execute a specific Active Template. There can be an unlimited number of auxiliary reports associated with each Active Template although none are required for execution. Auxiliary reports must be executed through VBA code whereas the ATM Engine executes driver reports automatically. Process Scheduler Service - Process that determines when an AT object is scheduled to be executed and then sends a message to the Process Dispatcher to start processing. Process Dispatcher - Process that houses the ATM Engine and upon receiving a message from the Process Scheduler Service will execute the appropriate application. Staging Tables - Read-only database of the temporary AT batches results generated after a successful AT Execution process. Investran Commit Processes - ATM process that transfers an Active Template's transaction batches from the temporary Staging table to Investran. Context Set of properties exposed by the ATM Engine that allows the AT developer to interact with the engine programmatically through VBA.

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Chapter

2
2. Getting Started in ATM
This chapter provides an introductory discussion of the ATM application. The chapter describes the major features and functions ATM provides, as well as the basics of navigating through the various panels and screens of the ATM application.

Launching ATM
When the ATM application is launched, a login form will appear. This form is similar to the login form in Investran or Report Wizard. Once the appropriate parameters have been entered, click OK to establish a connection to the Investran database. Please note that the appropriate security permissions must be granted to ATM users in the Investran Security Manager.

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Menu Options
A number of options are available from the applications menus. Many of these options also appear on various panels and pop-up menus available throughout the application. System Menu Button/Menu Option Change Database Refresh Tree Exit Purpose Brings up the Login form so a connection to a different database may be established.
Retrieves the Active Template information from the database to reflect any changes since the last Refresh or Login operation.

Closes the ATM application.

Process Maintenance Sub-Menu (Under System Menu) Button/Menu Option Process Notification Purpose Displays a dialog box that allows the user to set whether the system will display a notification when the batches have been generated, committed, or have failed. The user can also set the frequency of notifications.
Displays the status of the batch generation phase of an AT execution. Possible states include Pending, Running, Cancelled, and so on. Displays the status of the commit phase of an AT execution. Possible states include Pending, Running, Cancelled, and so on.

Batch Generation
Commit Transactions

Active Template Menu

Button/Menu Option Add Purpose

Creates a new Active Template.

Modifies the attributes of an existing Active Template.

Edit

Note: This option will not be available if a user is running the Active Template.
Deletes an existing Active Template.

Delete Duplicate Run Simulate

Note: This option will not be available if a user is running the Active Template. Creates a new Active Template that is a copy of an existing Active Template. Schedules the Active Template for execution. Executes the Active Template in a simulated environment.

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Journal Entry Menu

Button/Menu Option Add Purpose Defines a new Journal Entry in the Active Template.

Edit Delete Copy Paste

Move to Top Move Up Move Down Move to Bottom

Modifies the attributes of an existing Journal Entry. Deletes an existing Journal Entry. Copies the definition of a Journal Entry. Pastes the definition of a previously copied Journal Entry.
Moves the selected Journal Entry to the first position. Moves the selected Journal Entry up one position. Moves the selected Journal Entry down one position. Moves the selected Journal Entry to the last position.

Transaction Template Menu

Button/Menu Option Add Purpose Defines a new Transaction Template in the Active Template.

Edit Delete Copy Paste

Move to Top Move Up Move Down Move to Bottom

Modifies the attributes of an existing Transaction Template. Deletes an existing Transaction Template. Copies the definition of a Transaction Template. Pastes the definition of a previously copied Transaction Template.
Moves the selected Transaction Template to the first position. Moves the selected Transaction Template up one position. Moves the selected Transaction Template down one position. Moves the selected Transaction Template to the last position.

Parameters Menu
Button/Menu Option Purpose

Define

Creates a new Investran parameter. Any Allocation Rules, Report Wizard reports, or

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Active Templates may use the parameters created with this operation.

Add Edit
Delete

Adds a parameter to the Active Template. The parameter may be mandatory or optional and it may be assigned a default value. It may also be mapped to a property.

Modifies one of the Active Templates parameters.

Deletes one of the Active Templates parameters.

Driver Reports Menu

Button/Menu Option Purpose Adds a Report Wizard report to the Active Template as a driver report after the current position. Any report in a Public Read-only folder may be added to the Active Template. Adds a Report Wizard report to the Active Template as a driver report before the current position. Any report in a Public Read-only folder may be added to the Active Template. Deletes one of the Active Templates driver reports. Moves the selected driver report up one position. Moves the selected driver report down one position.

Insert After Insert Before

Delete Report Move Up Move Down

Auxiliary Reports Menu

Button/Menu Option Purpose Adds a Report Wizard report to the Active Template as an auxiliary report. Any report in a Public Read-only folder may be added to the Active Template. Deletes one of the Active Templates auxiliary reports.

Add
Delete

VBA Code Menu

Button/Menu Option Purpose Displays the VBA code associated with the given Active Template in the VBA Code Editor.

Show VBA Module Save VBA Module

Stores any modifications made to the VBA code.

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Active Template Attributes

There are a number of attributes associated with an Active Template. These attributes are defined when the Active Template is created and may be modified using the Edit option on the Active Template menu.

Add/Edit Active Template Panel

Attribute Active Template Name Batch Type Use VBA Purpose Defines the name of the AT. Defines the Batch Type for the batches generated by the AT. Defines if the AT uses Visual Basic for Applications. A locked AT can only be modified by the developer that locked it. This prevents the AT from being modified by another user. When this check box is checked, any errors that occur during the AT Execution Process will be ignored and the program will be allowed to complete. Valid transactions will be written to the Staging Table and all errors will be written to the Error Log. When this check box is not checked, the first error that occurs during the AT Execution Process will be written to the Error Log and the execution will be terminated.

Locked

Ignore Errors

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Attribute

Compatible with multicurrency Non-Memo JEs

Purpose Indicates whether the AT is compatible with multi-currency non-memo journal entries. If a user tries to run an AT that is not marked as compatible with multi-currency journal entries in an environment where multi-currency settings are enabled (where AllowMultiCcyNonMemoJEs is set to 1), the AT will fail. Indicates whether the AT is compatible with multi-currency memo journal entries. If a user tries to run an AT that is not marked as compatible with multi-currency journal entries in an environment where multi-currency settings are enabled (where AllowMultiCcyMemoJEs is set to 1), the AT will fail. An optional description of the AT. Any text entered in this field will populate the Batch Comments field for the batches generated by the AT. You can use the description parameters within the overall description text. The description parameters serve as placeholders which the ATM will replace with the corresponding value at runtime.

Compatible with multicurrency Memo JEs

Notes

Description

For example, if you enter Valuation as of <GLDate> for the description text and you run the AT with a GL date of 12/31/2007, the resulting batch will have the following batch comment, Valuation as of 12/31/2007. Status
An AT is in Draft status when it is first created. ATs are not available for execution when they are in Draft status. Once an AT has been tested and is ready for use, the status should be changed to Normal. System status is reserved for ATs developed by SunGard Investran.

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Navigation
Database Connection Once a connection is established, all the information relating to existing Active Templates will be retrieved from the database. A drop-down list displays all of the available Active Templates. Information about the selected AT is displayed in a tree format in the left panel of ATM. The right panel will display information about the current database connection.

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Active Templates Selecting an Active Template from the list of available ATs will display information about the selected AT in a tree format in the left panel of ATM. Selecting the AT will also update the right panel to display the attributes of that Active Template. This information identifies the creator of the AT, the date and time the AT was created, the user that last modified the AT, the date and time of the last modification, any notes describing the AT, the Batch Type which will be used by the AT, and the ATs status (Draft, Normal, or System). Active Templates may be added, edited, duplicated, deleted, simulated and executed from this panel.

Each Active Template node in the tree may be expanded by clicking on the +. This allows the user to view the Parameters, Driver Reports, Auxiliary Reports, Journal Entries, and Transaction Templates associated with an AT. Selecting any of the items in the left panel, such as Parameters, Driver Reports, Auxiliary Reports, Journal Entries, or Transaction Templates for a given AT will provide detailed information in the right panel related to the selected item.

10

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Parameters Selecting Active Template Parameters displays the list of Parameters that have been configured for use by the Active Template. Parameters are used to pass values to the Active Template at run time (such as Legal Entity and Transfer Date). Parameters may be added, edited and deleted from this panel.

11

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Driver Reports Selecting Active Template Driver Reports displays the list of reports that have been configured for use by the Active Template. The Driver Reports are used as input by the Active Templates. These reports ultimately determine the number of transactions the AT may potentially generate. An AT may have from zero up to three Driver Reports. Driver Reports may be inserted, deleted and moved from this panel. The columns from the driver report(s) are mapped to properties of the Active Template. This mapping is relative to a specific level (such as Batch, Journal Entry, or Transaction Template).

Report nodes in the tree may be expanded further to display information about the Columns and Parameters used in the report.

12

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Auxiliary Reports Selecting Auxiliary Reports from the tree structure displays the list of reports that have been configured for use by the Active Template. Through VBA, the developer can use these reports to retrieve additional Investran data required by the AT to generate the transactions. Auxiliary reports may be added and deleted from this panel.

Report nodes in the tree may be expanded further to display information about the Columns and Parameters used in the report.

13

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Journal Entries Selecting Journal Entries from the tree structure displays the list of Journal Entries that have been defined for the Active Template. The Journal Entries created in this screen serve as a template for the batches that will be generated by the Active Template. Journal Entries may be added, edited, deleted, copied and pasted from this panel. In addition, the order of the Journal Entries may be modified from this panel.

14

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Transaction Templates Selecting Transaction Templates from the tree structure displays the list of Transaction Templates that have been defined for the each Journal Entry. The Transaction Templates created in this screen serve as a template for the Journal Entries that will be generated by the Active Template. Transaction Templates may be added, edited, deleted, copied and pasted from this panel. In addition, the order of the Transaction Templates may be modified from this panel.

15

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Visual Basic for Applications (VBA) Some very simple Active Templates do not require the use of VBA. However, most ATs require certain business logic, at times very complex, that needs to be implemented with VBA code. The use of VBA code or not, must be explicitly specified for the Active Template properties. To do this, check the Use VBA check box that appears in the Active Template Properties dialog box.

If the necessity of VBA code was not foreseen when the AT was created, the developer can go back and edit the desired Active Template and check the Use VBA box.

16

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

The VBA code needed to implement the process logic is stored in the VBA Module associated with the AT. If the Active Template uses VBA, the VBA Module may be displayed using the VBA Code Show VBA Editor menu sequence.

17

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

The VBA Code Editor appears in the lower half of the main panel of the ATM application by default. The VBA Code Editor provides many of the features available from most programming development environments. Clicking on the Maximize Module button will maximize the VBA Code Editor window.

Note: When the VBA code window is maximized, make sure to restore it to its normal size before switching to any other open application. If you ever switch from ATM to another Windows application while the VBA code is maximized, you will not be able to cycle through the open tasks, by using ALT+TAB and return to ATM. In such a case, please minimize all open applications until you return to the ATMs VBA code window, restore it to its normal size, and then continue working as usual.

18

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Chapter

3
3. Classes Commonly Used in VBA
Before exploring the use of VBA in Active Templates, there are some classes and objects the ATM developer should be familiar with. These include the RWReport class and the InvestorSet class. Also, the Application object is available to represent the Active Template itself, and the Context object is available as a property of the Application object. The Context object is the mechanism through which information is passed back and forth between the ATM Engine and the VBA code.

The Application
The Application class has a single object instance created by the ATM Engine. This object represents the Active Template itself. It is used to perform some basic functions and get information about this Active Template, such as a list of the auxiliary reports. It contains pre-defined events that provide the hooks for inserting developer functionality into the Active Template process with VBA. Public Class Definition
<<class>> Application CancelExecution() Log(StringToLog : String) NewInvestorSet(ByVal Index : Long) : Object <<Get>> Context() : Object <<Get>> Reports(ByVal Index : Long = -1, ByVal BookName : String, ByVal ReportName : String) : Object <<Get>> LogFileName() : String <<Get>> DriverReportRecordCount() : Long <<Get>> ProcessID() : Long <<Get>> ActiveTemplateID() : Long Application_BeforeBatch() Application_BeforeJournalEntry(JEIndex : Long) Application_BeforeTransaction(JEIndex : Long, TXIndex : Long) Application_AfterTransaction(JEIndex : Long, TXIndex : Long, Result : Object)

19

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Properties <<Get>>ActiveTemplateID(): Long Returns the static ID of the AT. <<Get>> Context(): Context. Returns the object used for all communication between the ATM Engine and VBA. See next class definition. <<Get>>DriverReport() : RWReport Returns a reference to a clone of the driver report. <<Get>>DriverReportCurrentRow Returns the row number for the current driver report row being processed by the AT. <<Get>>DriverReportRecordCount(): Long Returns the number of rows in the driver report currently driving the AT. <<Get>>LogFileName(): String Returns the name of the debugging log assigned by the ATM Engine. <<Get>>ProcessID(): Long Returns the process ID of the currently running AT Execution. <<Get>>Reports(): RWReport Returns a Report Wizard report object. Provides access to the auxiliary reports of the AT. Can be requested by index, or by book and report name.

Methods CancelExecution() Immediately cancels the execution of the AT, with an unsuccessful completion status. Log(StringToLog As String) Logs a string to the debugging log. NewInvestorSet(ByVal Index as Long): InvestorSet Creates an instance of an Investor Set (see class definition below), with the valid investor IDs for this database already filled in the InvestorId array. The amounts and quantities for all investors are initially zero.

Events Application_BeforeAT(): Variant Fired once before any other code related to the AT is executed. This is raised prior to the execution of the driver report. Application_BeforeBatch() Fired before each new batch is created. This occurs at the beginning of the application and each time a Batch level column changes in a driver report.

20

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Application_BeforeJournalEntry(JEIndex As Long) Fired before each new journal entry is created. JEIndex represents the index of the JE in the template, starting at one. This occurs for each journal entry found in the template, at the beginning of the application and each time a Journal Entry level column changes in a driver report. Application_BeforeTransaction(JEIndex As Long, TXIndex As Long) Fired before each new transaction is created. JEIndex represents the JE index in the template, and TXIndex represents the index of the transaction template in that journal entry. This event fires one to many times for each row of the driver report once for each transaction template in the hierarchy. Application_AfterDriver(): Variant Fired after the driver report is processed but before the first call to BeforeBatch, BeforeJournalEntry, BeforeTransaction, AfterTransaction, AfterJournalEntry, or AfterBatch. Application_AfterTransaction(JEIndex As Long, TXIndex As Long, Result As InvestorSet) Fired after the Allocation Rule is applied for a transaction row, but before the final save to the database. JEIndex and TXIndex are the same as in the BeforeTransaction. The Result investor set represents the allocation to investors as already performed by the Allocation Rule, and allows for modifications (or the complete allocation in the case of user-defined allocations) in the AfterTransaction event before saving to the database. Application_AfterJournalEntry(JE Index as Long): Variant Fired after each new journal entry is created. JEIndex represents the index of the JE in the template, starting at one. This occurs for each journal entry found in the template and each time a Journal Entry level column changes in a driver report. Application_AfterBatch(): Variant Fired after each new batch is created. This occurs each time a Batch level column changes in a driver report. Application_AfterAT(AT Successful as Boolean): Variant Fired after the AT has been executed (after all driver report rows have been processed and all other events have been raised). This event will be raised whether the AT is successful or not.

The Context
The Context object is a top-level object that exposes all the properties needed by the ATM Engine at run time. The Context object is instantiated by the ATM Engine and passes around as a property of the Application object. Not all properties of the Context object need to be populated all the time, as they depend on the purpose of each specific AT. There are, however, certain properties that should always be populated with the correct values, or the ATM Engine will fail during its execution. The properties of the Context object are used for creating the transaction records.

21

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Public Class Definition

Properties <<Let>> Value(Name : String, ByVal Value : Variant) Sets the value of the parameter referred to as an argument. This array property is used to store any parameters that do not directly map to an existing Context property. <<Get>> Value(Name : String) : Variant Returns the value of the parameter or property specified, by name, as an argument. This property is mainly used for reading the parameters passed at run-time to the ATM through the dialog that do not directly map to Context properties. This property is also useful for accessing ATM properties for which the Context does not offer a direct method of access as documented in this section as well as offering an alternative method for accessing many Context properties. See the Appendix for a list of the ATM properties which can be accessed using this method along with their corresponding data type. <<Let>> LegalEntity(LegalEntity : Variant) Sets the value for the Legal Entity (ID) to be used by the ATM Engine. This property is required. <<Get>> LegalEntity() : Variant Returns the ID of the Legal Entity being used by the ATM Engine.

22

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

<<Let>> GLDate(GLDate : Variant) Sets the value for the GL Date used by the ATM Engine. This property is required. <<Get>> GLDate() : Variant Returns the GL Date value being used by the ATM Engine. <<Let>> Deal(Deal : Variant) Sets the Deal (ID) to be used by the ATM Engine. <<Get>> Deal() : Variant Returns the Deal ID being used by the ATM Engine. <<Let>> Position(Position : Variant) Sets the Position (ID) to be used by the ATM Engine. <<Get>> Position() : Variant Returns the Position ID being used by the ATM Engine. <<Let>> Account(Account : Variant) Sets the Account Number to be used by the ATM Engine. <<Get>> Account() : Variant Returns the Account Number being used by the ATM Engine. <<Let>> Pool(Pool : Variant) Sets the Pool ID to be used by the ATM Engine. <<Get>> Pool() : Variant Returns the Pool ID being used by the ATM Engine. <<Let>> CompanySubIssue(CompanySubIssue : Variant) Sets the Company Sub-Issue ID to be used by the ATM Engine. In the Investran user interface, the term Company Sub-Issue is now known as Income Security however, Company Sub-Issue has been retained in the ATM for backward compatibility. <<Get>> CompanySubIssue() : Variant Returns the Company Sub-Issue ID being used by the ATM Engine. In the Investran user interface, the term Company Sub-Issue is now known as Income Security however, Company Sub-Issue has been retained in the ATM for backward compatibility. <<Let>> Lot(Lot : Variant) Sets the Lot ID to be used by the ATM Engine. <<Get>> Lot() : Variant Returns the Lot ID being used by the ATM Engine.

23

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

<<Let>> EffectiveDate(EffectiveDate : Variant) Sets the Effective date of the transactions created by the ATM Engine. This property is required. <<Get>> EffectiveDate() : Variant Returns the Effective Date to be used by the ATM Engine when creating transactions. <<Let>> Amount(Amount : Variant) Sets the total Amount (in Local Currency) to be booked by the ATM Engine. <<Get>> Amount() : Variant Returns the Total Amount (in Local Currency) to be used when booking a transaction. <<Let>> AmountScale(AmountScale : Variant) Sets the number of decimal places to be used when booking an Amount (Local Currency). <<Get>> AmountScale() : Variant Returns the decimal places to be used when booking an Amount (in Local Currency). <<Let>> AmountTotalScale(AmountTotalScale : Variant) Sets the number of decimal places to be used for the total Amount of the transaction. This property is only relevant if you want the precision of the total amount to be less than the precision for the individual investors. Otherwise, just use AmountScale. <<Get>> AmountTotalScale() : Variant Returns the total amount number of decimal places when different than precision for individual investors. <<Let>> LEAmount(LEAmount : Variant) Sets the amount to be booked in the Legal Entity currency. <<Get>> LEAmount() : Variant Returns the amount to be booked in the Legal Entity currency. <<Let>> LEAmountScale(LEAmountScale : Variant) Sets the number of decimal places to be used when booking an amount (in the Legal Entity currency). <<Get>> LEAmountScale() : Variant Returns the number of decimal places to be used when booking an amount (in the Legal Entity Currency). <<Let>> LEAmountTotalScale(LEAmountTotalScale : Variant) Sets the number of decimal places to be used for the total LEAmount of the transaction. Only relevant if you want the precision of the total LE amount to be less than the precision for the individual investors, otherwise, use LEAmountScale. <<Get>> LEAmountTotalScale() : Variant Returns the total LE amount number of decimal places when different than precision for individual investors.

24

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

<<Let>> Quantity(Quantity : Variant) Sets the number of shares involved in the transaction. <<Get>> Quantity() : Variant Returns the number of shares involved in the transaction. <<Let>> QuantityScale(QuantityScale : Variant) Sets the number of decimal places to be used when booking the number of shares for a transaction. <<Get>> Quantity() : Variant Returns the number of decimal places to be used when booking the number of shares for a transaction. <<Let>> QuantityTotalScale(QuantityTotalScale : Variant) Sets the number of decimal places to be used for the total Quantity of the transaction. This property is only relevant if you want the precision of the total quantity to be less than the precision for the individual investors. Otherwise, just use QuantityScale. <<Get>> QuantityTotalScale() : Variant Returns the total quantity number of decimal places when different than precision for individual investor. <<Let>> TransactionCurrency(TransactionCurrency : Variant) Sets the currency (ID) of the transaction. <<Get>> TransactionCurrency() : Variant Returns the currency (ID) of the transaction. <<Let>> TransactionTypeDebit(TransactionTypeDebit : Variant) Sets the transaction type (ID) to be used when booking a debit transaction. <<Get>> TransactionTypeDebit() : Variant Returns the transaction type (ID) being used when booking a debit transaction. <<Let>> TransactionTypeCredit(TransactionTypeCredit : Variant) Sets the transaction type (ID) to be used when booking a credit transaction. <<Get>> TransactionTypeCredit() : Variant Returns the transaction type (ID) being used when booking a credit transaction. <<Let>> NonDomTransactionTypeDebit(NonDomTransactionTypeDebit : Variant) Sets the transaction type (ID) to be used when booking a non-dominant debit transaction. <<Get>> NonDomTransactionTypeDebit() : Variant Returns the transaction type (ID) being used when booking a non-dominant debit transaction. <<Let>> NonDomTransactionTypeCredit(NonDomTransactionTypeCredit : Variant) Sets the transaction type (ID) to be used when booking a non-dominant Credit transaction.

25

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

<<Get>> NonDomTransactionTypeCredit() : Variant Returns the transaction type (ID) being used when booking a non-dominant Credit transaction. <<Let>> IsDebit(IsDebit : Variant) Set to True if debit, False if credit. Setting this value is generally not necessary and is ignored if sign of amount determines value. <<Get>> IsDebit() : Variant Returns True if this is a debit transaction, False if credit. <<Let>> AllocationRule(AllocationRule : Variant) Sets the Allocation Rule (ID) to be used when booking a transaction. <<Get>> AllocationRule() : Variant Returns the Allocation Rule (ID) being used when booking a transaction. <<Let>> BatchStatus(BatchStatus : Variant) Sets the Batch Status (Draft, Held, Posted) to be used when creating the batch. <<Get>> BatchStatus() : Variant Returns the Batch Status used when creating the batch. <<Let>> TransactionComments(Value : Variant) Sets a user-defined remark associated with a transaction. <<Get>> TransactionComments() : Variant Returns the user-defined remark associated with the transaction. <<Let>> GLRef1(Value : Variant) Sets the GL reference string associated with the transaction. <<Get>> GLRef1() : Variant Returns the GL Reference string associated with the transaction. <<Let>> PIKCompanySubIssue(Value : Variant) Sets the Paid-In-Kind sub-issue for Paid-In-Kind income transactions. In the Investran user interface, the term Paid-In-Kind Sub-Issue is now known as Paid-In-Kind Income Security however, the term Paid-In-Kind Sub-Issue has been retained in the ATM for backward compatibility. <<Get>> PIKCompanySubIssue() : Variant Returns the Paid-In-Kind sub-issue. In the Investran user interface, the term Paid-In-Kind Sub-Issue is now known as Paid-In-Kind Income Security however, the term Paid-In-Kind Sub-Issue has been retained in the ATM for backward compatibility. <<Let>> ExpirationDate(Value : Variant) Sets the expiration date for a hedged security.

26

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

<<Get>> ExpirationDate() : Variant Returns the expiration date for a hedged security. <<Let>> Hedged(Value : Variant) Set to true to indicate that this is a hedge transaction. Used in conjunction with ExpirationDate field. <<Get>> Hedged() : Variant Returns whether this is a hedge transaction. <<Let>> CostBasisAmount(Value : Variant) Sets a cost basis amount for security. Useful for transactions in which the amount of the transaction differs from the cost basis for tax or other purposes. <<Get>> CostBasisAmount() : Variant Returns the cost basis amount of the transaction security. <<Let>> JournalEntryType(Value : Variant) Sets the user-defined journal entry type attached to the transaction. <<Get>> JournalEntryType(): Variant Returns the user-defined journal entry type. <<Let>> UserDefinedDate1(Value : Variant) Sets a date to the transaction with user-defined meaning. <<Get>> UserDefinedDate1(): Variant Returns the user-defined date. <<Let>> UserDefinedID1(Value : Variant) Sets an ID to the transaction with user-defined meaning. <<Get>> UserDefinedID1(): Variant Returns the user-defined ID. <<Let>> UserDefinedLookup1(Value : Variant) Sets a lookup to the transaction with user-defined meaning. <<Get>> UserDefinedLookup1(): Variant Returns the user-defined lookup. <<Let>> UserDefinedLookup2 (Value : Variant) Sets a lookup to the transaction with user-defined meaning. <<Get>> UserDefinedLookup2(): Variant Returns the user-defined lookup.

27

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

<<Get>> AfterExecutedSQLCommands(): Variant Returns an SQL statement collection which can be appended to and modified. The SQL statements will be executed after the AT execution is complete, after being saved to the Staging database before the Commit process. Note: When executing two or more SQL UPDATE commands, the UPDATE command should always be enclosed between BEGIN TRANSACTION and COMMIT TRANSACTION instructions to avoid concurrency issues. This is an issue inherent to Microsoft SQL code.

<<Get>> BeforeCommitSQLCommands(): Variant Returns a SQL statement collection which can be appended to and modified. The SQL statements will be executed just before the Commit process. Note: When executing two or more SQL UPDATE commands, the UPDATE command should always be enclosed between BEGIN TRANSACTION and COMMIT TRANSACTION instructions to avoid concurrency issues. This is an issue inherent to Microsoft SQL code.

<<Get>> AfterCommitedSQLCommands(): Variant Returns a SQL statement collection which can be appended to and modified. The SQL statements will be executed after the Commit process. Note: When executing two or more SQL UPDATE commands, the UPDATE command should always be enclosed between BEGIN TRANSACTION and COMMIT TRANSACTION instructions to avoid concurrency issues. This is an issue inherent to Microsoft SQL code.

RWReport Class
In many occasions, the data retrieved by the Driver report is not sufficient to correctly create the transactions, and additional reports may be necessary to obtain all the data. Differently from the driver report, which is executed by the ATM engine, the Auxiliary reports must be invoked by the developer in VBA. The RWReport component encapsulates a Report Wizard report and its related functionality. An object of this type is used to run Report Wizard reports and retrieve data from the Investran database.

28

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Public Class Definition

<<C lass M odule>> RWReport << Le t>> P arame te r(P ara meterName : S tring , V alue : V ariant) R un(O ptio nal F orceRefresh : Bool ean = F alse) << Get> > Row s () : Long << Get> > C ols () : Long << Get> > C olN ame(ColInd ex : Long) : String << Get> > C olT y pe(C o lIn dex : Long) : S tri ng << Get> > C olI ndex(ColN ame : S tring) : Lo ng << Get> > C olT otal(C olI ndex : Long ) : V ariant << Get> > C ell(Row I ndex : Long , C olI ndex : Lon g) : V ariant << Get> > P aramete rC ount() : Lo ng << Get> > P aramete rN ame(P arame te rInde x : Lo ng) : S trin g << Get> > P aramete rTy pe(P arame terInde x : Lo ng) : Strin g << Get> > P aramete rD efaul tV alu e(Pa ra met erIn dex : Long) : Variant << Get> > P aramete rD efaul tLook UpText(P ara meterInd ex : Long) : Varia nt

Properties <<Get>> Cell(RowIndex : Long, ColIndex : Long) : Variant Returns the cell at the given row and column index. <<Get>> ColIndex(ColName : String) : Long Returns the column index of the named column. <<Get>> ColName(ColIndex : Long) : String Returns the column name at the given column index. <<Get>> Cols() : Long Returns the number of columns in the report. <<Get>> ColTotal(ColIndex : Long) : Variant Returns the total for the given column index. <<Get>> ColType(ColIndex : Long) : String Returns the type for the given column index. <<Let>> Parameter(ParameterName : String, Value : Variant) Sets the value of the named parameter. <<Get>> ParameterCount() : Long Returns the number of parameters in the report. <<Get>> ParameterDefaultLookUpText(ParameterIndex : Long) : Variant Returns the parameter default lookup text for the given parameter index.

29

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

<<Get>> ParameterDefaultValue(ParameterIndex : Long) : Variant Returns the parameter default value for the given parameter index. <<Get>> ParameterName(ParameterIndex : Long) : String Returns the name for the given parameter index. <<Get>> ParameterType(ParameterIndex : Long) : String Returns the parameter type for the given parameter index. <<Let>> RestoreFilterParameter(ParameterName : String) Restores the report filters to those stored in the report definition for all filters using the named parameter. <<Get>> Rows() : Long Returns the number of rows in the report. <<Let>> SetOnlyNullsFilterParameter(ParameterName : String) Sets the report filters to Only Nulls for those filters using the named parameter.

Methods Run(Optional ForceRefresh : Boolean = False) Executes the report and stores the results internally for retrieval using the objects properties. Passing a value of true for the ForceRefresh parameter forces the report to execute even if the results have been cached.

Example The following code snippet illustrates how to execute and use the values returned by a Report Wizard report. The actual data and values of the code snippet are not important, rather the approach used to invoke the report and obtain the values.
Dim Rpt As RWReport Dim Value As Variant Dim i As Long 'Report object 'Storage for values retrieved from report 'For loop control variable

'Create the report object specifying where the report could be found Set Rpt = Application.Reports(, REPORTS_FOLDER, REPORT_NAME) 'pass a parameter needed by the report Rpt.Parameter("Legal Entity") = Application.Context.LegalEntity 'Execute the report Rpt.Run 'Did the report return any row? If Rpt.Rows <> 0 Then Rpt.MoveFirst For i = 1 to Rpt.Rows 'retrieve the value in the third column, for each row. Value = CLng(Rpt.Cell(i, 3)) '..... 'Logic goes here '..... Next i 'next investor Else 'report did not return any row, is this an error? End If

30

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

InvestorSet Class
An object of InvestorSet Class represents all the investors in a given Legal Entity along with their corresponding allocations. A local amount, a Legal Entity amount, and a quantity may be stored for each investor in the InvestorSet. Public Class Definition
<<C lass M odule>> Inv estorSet <<G et>> C ount() : Long <<G et>> G P C ount() : Long <<G et>> Index(By V al Inv estorID : V ariant) : Long <<G et>> Inv estorID(By V al Index : Long) : S tring <<G et>> Inv estorN ame(By V al Index : Long) : S tring <<G et>> IsG P(By V al Index : Long) : Boolean <<G et>> IsP articipant(By V al Index : Long) : Boolean <<G et>> V ehicleN ame(By V al Index : Long) : S tring <<Let>> A mount(By V al Index : Long, v al : Double) <<G et>> A mount(By V al Index : Long) : Double <<G et>> TotalA mount(O ptional TotalScale : Integer = 2) : Double <<Let>> LE A mount(By V al Index : Long, v al : Double) <<G et>> LEA mount(By V al Index : Long) : Double <<G et>> TotalLE A mount(O ptional By V al TotalS cale : Integer = 2) : Double <<Let>> Q uantity (By V al Index : Long, v al : Double) <<G et>> Q uantity (By V al Index : Long) : Double <<G et>> TotalQ uantity (O ptional TotalScale : Integer = 2) : Double <<Let>> RoundS cale(v al : Integer) <<G et>> RoundScale() : Integer <<Let>> V alue(By V al Index : Long, v al : Double) <<G et>> V alue(By V al Index : Long) : Double <<G et>> Total(O ptional By V al TotalS cale : Integer = 2) : D ouble A llocateS ets(By V al A mount : Double, By V al LE A mount : Double, By V al Q uantity : Double) RoundSets(By V al A mountScale : Integer, By V al A mountTotalS cale : Integer, By V al LEA mountS cale : Integer, By V al LE A mountTotalS cale : Integer, By V al Q uantity S cale : Integer, By V al Q uantity TotalS cale : Integer) C opy S et(cis : Inv estorSet) A dd(cis : Inv estorSet) S ubtract(cis : Inv estorS et) S plit(A mount : Double) S plitG P LP (A mount : Double, G P P ercent : Double, Ratios : Inv estorSet) A ccumulate(By Ref TotalG P : Double, By Ref TotalLP : D ouble) : Double C opy C olumn(rpt : RWReport, C olN ame : String, O ptional A ggregate : Boolean = True) A pply P ercentage(ExactTotal : Double, P ercent : D ouble) ToP ercentage()

Properties <<Get>> Count() : Long Returns the number of valid investors in the InvestorSet. <<Get>> GPCount() : Long Returns the number of valid investors in the InvestorSet whose Investor Type is General Partner (GP) on the Investor Specific panel. <<Get>> Index(ByVal InvestorID : Variant) : Long Returns the index within the InvestorSet associated with the given Investor Specific ID. <<Get>> InvestorID(ByVal Index : Long) : String Returns the Investor Specific ID associated with the given InvestorSet index. <<Get>> InvestorName(ByVal Index : Long) : String Returns the Investor Name associated with the given InvestorSet index. <<Get>> IsGP(ByVal Index : Long) : Boolean Indicates if the investor at the given InvestorSet index has an Investor Type set to General Partner (GP) on the Investor Specific panel.

31

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

<<Get>> IsParticipant(ByVal Index : Long) : Boolean Indicates if the Vehicle associated with the investor at the given InvestorSet index is a Participant Vehicle. <<Get>> VehicleName(ByVal Index : Long) : String Returns the name of the Vehicle associated with the investor at the given InvestorSet index. <<Let>> Amount(ByVal Index : Long, val : Double) Sets the local amount for the investor at the given InvestorSet index. <<Get>> Amount(ByVal Index : Long) : Double Returns the local amount for the investor at the given InvestorSet index. <<Get>> TotalAmount(Optional TotalScale : Integer = 2) : Double Returns the sum of all the local amounts for all the investors in the InvestorSet rounded to the number of decimal places indicated in the TotalScale parameter. <<Let>> LEAmount(ByVal Index : Long, val : Double) Sets the Legal Entity amount for the investor at the given InvestorSet index. <<Get>> LEAmount(ByVal Index : Long) : Double Returns the Legal Entity amount for the investor at the given InvestorSet index. <<Get>> TotalLEAmount(Optional TotalScale : Integer = 2) : Double Returns the sum of all the Legal Entity amounts for all the investors in the InvestorSet rounded to the number of decimal places indicated in the TotalScale parameter. <<Let>> Quantity(ByVal Index : Long, val : Double) Sets the quantity for the investor at the given InvestorSet index. <<Get>> Quantity(ByVal Index : Long) : Double Returns the quantity for the investor at the given InvestorSet index. <<Get>> TotalQuantity(Optional TotalScale : Integer = 2) : Double Returns the sum of all the quantities for all the investors in the InvestorSet rounded to the number of decimal places indicated in the TotalScale parameter. <<Let>> RoundScale(val : Integer) This property is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this property should be avoided as it may be removed in the future. <<Get>> RoundScale() : Integer This property is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this property should be avoided as it may be removed in the future. <<Let>> Value(ByVal Index : Long, val : Double) This property is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this property should be avoided as it may be removed in the future.

32

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

<<Get>> Value(ByVal Index : Long) : Double This property is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this property should be avoided as it may be removed in the future. <<Get>> Total(Optional ByVal TotalScale : Integer = 2) : Double This property is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this property should be avoided as it may be removed in the future.

Methods AllocateSets(ByVal Amount : Double, ByVal LEAmount : Double, ByVal Quantity : Double) This method distributes the given local amount, Legal Entity amount, and quantity pro-rata among the investors in the InvestorSet. This allocation is based on the local amount, Legal Entity amount, and quantity values for each of the investors in the InvestorSet. RoundSets(ByVal AmountScale : Integer, ByVal AmountTotalScale : Integer, ByVal LEAmountScale : Integer, ByVal LEAmountTotalScale : Integer, ByVal QuantityScale : Integer, ByVal QuantityTotalScale : Integer) This method rounds the local amounts, Legal Entity amounts, and quantities for each the investors in the InvestorSet. CopySet(cis : InvestorSet) Copies the local amounts, Legal Entity amounts, and quantities for each of the investors from the given InvestorSet to the current InvestorSet. Add(cis : InvestorSet) Adds the local amounts, Legal Entity amounts, and quantities from the given InvestorSet to the current InvestorSet for each the investors. Subtract(cis : InvestorSet) Subtracts the local amounts, Legal Entity amounts, and quantities in the given InvestorSet from the current InvestorSet for each the investors. Split(Amount : Double) This method is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this method should be avoided as it may be removed in the future. SplitGPLP(Amount : Double, GPPercent : Double, Ratios : InvestorSet) This method is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this method should be avoided as it may be removed in the future. Accumulate(ByRef TotalGP : Double, ByRef TotalLP : Double) : Double This method is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this method should be avoided as it may be removed in the future. CopyColumn(rpt : RWReport, ColName : String, Optional Aggregate : Boolean = True) This method is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this method should be avoided as it may be removed in the future.

33

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

ApplyPercentage(ExactTotal : Double, Percent : Double) This method is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this method should be avoided as it may be removed in the future. ToPercentage() This method is considered obsolete and it is supported solely for backward compatibility with Active Templates developed in ATM 4.2. Use of this method should be avoided as it may be removed in the future.

Example The following code snippet indicates how to retrieve the correct Investor Index in the InvestorSet object given the Investor Specific ID, and set the local and LE amounts for this investor.
Dim InvSet As InvestorSet 'InvestorSet Object Dim InvIdx As Long 'InvestorSet Index Dim InvSpecID As Long 'Investor Specific ID '..... 'Create the InvestorSet object Set InvSet = Application.NewInvestorSet 'somehow we determine the Investor Specific ID 'that we want to locate in the InvestorSet object InvSpecID = 1234 'pass the Investor Specific ID as a parameter to 'the Index Method InvIdx = InvSetCR.Index(InvSpecID) 'now the InvIdx contains the index of Investor 1234 'within the InvSet data structure 'we can now access any property for this investor InvSet.Amount(InvIdx) = 12456.99 InvSet.LEAmount(InvIdx) = 98765.33

34

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Chapter

4
4. Active Template Examples
In theory, the simplest Active Template does not require VBA code. A combination of parameters and/or a driver report fills in all information necessary for creating the batch transactions. However, such codeless ATs are restricted in what they can do and therefore rare. In this section, we will analyze only Active Templates that utilize VBA code. The first example will not use a driver report. This type of Active Template can be used to create a single set of journal entries and transactions, based on parameters to the template, as well as information gathered from auxiliary reports. Our second example will use a driver report. The driver report allows us to retrieve a set of records based on AT parameters, and then create journal entries and transactions for each record returned by the driver report.

Active Template with No Driver Report

In this example, we will create a Buy Active Template. The purpose of this AT is to create the journal entry for the purchase of a company issue. The journal entry will consist of the dominant Purchase transaction, as well as the non-dominant balancing entry.

35

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Create the Active Template and Assign Attributes Create a new Active Template by using the Add New Active Template button or menu item. The attributes window will appear for assigning template attributes, including the name by which the Active Template will be known. The batch type, and description will be assigned to each of the batches created by the Active Template (in this case, one batch per run of the AT). The AT will originally be created in Draft status, which must be changed to Normal status before use.

36

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Define the Journal Entry/Transaction Templates Next, we will define the template of journal entries and transactions to be created by the AT. In a no driver report, the Active Template will attempt to create a journal entry and transaction for each element created in this template. In our example, one journal entry will be created. Note that the Allow zero transactions check box determines whether zero transactions will be created if it is not checked, any transactions with both zero local and LE amounts are automatically eliminated from the output of the AT.

Next, we will define the transaction templates. In this example, we will create one transaction for the dominant entry and another transaction for the non-dominant entry.

37

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

After creating the transaction template, we can view and expand our tree of journal entries and transaction templates.

38

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Define the AT Parameters The user of an Active Template can be prompted for parameters each time the AT is run. These parameters can then be used as parameters to driver or auxiliary reports, be used in calculations of the VBA, or be directly mapped to properties in the output transaction. The following screen shows a parameter as it is being defined. Note that the parameter type (and lookup item if relevant) is defined when the parameter is added use the ellipses button here if an appropriate parameter has not already been defined in the database. A default Value can be defined, in which case the user will have the option at AT run-time to accept the default or override it. The Is Mandatory check box requires the user to enter a value for this parameter when the AT is run. The Map To a Property drop down will automatically map this parameter to a property in the Context object.

A parameter may be created at the batch, journal entry, or transaction level, depending on the property that the parameter is mapped to. At run-time, the parameters at all levels are presented to the user for input. To view a list of the batch-level parameters in the main screen, highlight the Parameters tree node.

39

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

In our example, additional parameters are defined at the journal entry level and transaction levels. The following screen shot shows some additional parameters for out Buy AT that are defined at the journal entry level.

40

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Again, where you must define a parameter is determined by the transaction property to which you are directly mapping it. Alternatively, all parameters could be defined at the batch level and assigned to properties where appropriate in the VBA code. Regardless, all parameters are combined and displayed to the user for input at AT run time:

Add VBA Code So far, we have defined the input (parameters and reports) of our AT and the output (journal entries and transactions) format. The VBA code is used to manipulate and calculate the input into the proper output content. The ATM Engine has the following pre-defined events: BeforeAT BeforeBatch BeforeJournalEntry BeforeTransaction AfterAT AfterBatch

41

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

AfterDriver AfterJournalEntry AfterTransaction

In the case of our Buy AT, BeforeBatch and BeforeJournalEntry are each called once. The BeforeTransaction and AfterTransaction events are called twice each since our template contains two transactions. Below is the BeforeBatch event for our AT. This event is used for processing done once for each batch. In our case, we validate the input parameters. Note the use of the very important object Application.Context. This object contains the properties corresponding to the transaction fields which will be created, and is the way we pass data back and forth from the VBA code to the ATM Engine. In this example, we reference EffectiveDate and GLDate, which are already initialized based on mapped parameters (see section above where we created these parameters).
Public Sub Application_BeforeBatch() 'Make sure dates are valid ValidateDates End Sub '-- Make sure Trade Date (GL Date) and Settlement Date (Effective Date) are valid Sub ValidateDates ' Make sure Settlement Date is >= Trade Date If Application.Context.EffectiveDate < Application.Context.GLDate Then 'Err.Raise vbObjectError + 6001, "AT: Application_BeforeBatch", "Settlement Date must not be before Trade Date" Application.Context.EffectiveDate = DateAdd("d", 3, Application.Context.GLDate) End If ' Make sure Settlement Date is not on a weekend Select Case Weekday(Application.Context.EffectiveDate) Case 1 ' It's Sunday so add 1 day to make it Monday Application.Context.EffectiveDate = DateAdd("d", 1, Application.Context.EffectiveDate) Case 7 ' It's Saturday so add 2 days to make it Monday Application.Context.EffectiveDate = DateAdd("d", 2, Application.Context.EffectiveDate) Case Else ' Do Nothing End Select End Sub

The code below shows the constant definition and BeforeTransaction event for our application. Note that we can retrieve those parameters that were not directly mapped to Context properties using the Value array of the Context object. Note also that the BeforeTransaction event contains parameters for the JournalEntry Number and Transaction Number. These are numbered sequentially from 1 based on our journal entry/transaction tree. In our case, because we have two transaction entries, the BeforeTransaction event will be fired twice: TXIndex = 1 for the dominant transaction; and TXIndex = 2 for the non-dominant.

42

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Option Explicit ' Constants for Allocation Rules Private Const cstAR_NonDominant As Long = 0 Private Const cstAR_NoAllocation As Long = 1 Private Const cstAR_UserProvided As Long = 2 ' Report related Constants Private Const cstATMFolder Private Const cstRptBuyATDealAttr ' Parameter related Constants Private Const cstParamPortfolio Private Const cstParamIssue Private Const cstParamTaxLot Private Const cstParamQuantity Private Const cstParamTradePrice Private Const cstParamTradeDate Private Const cstParamSettlementDate Private Const cstParamCommission Private Const cstParamOther Private Const cstParamFXRate Private Const cstParamTTCredit Private Const cstParamTTDebit

' Non Dominant Alloc Rule ID ' No Allocation Alloc Rule ID ' User Provided Alloc Rule ID

As String = "ATM Reports" As String = "BuyATDealAttr"

As As As As As As As As As As As As

String String String String String String String String String String String String

= = = = = = = = = = = =

"01. Portfolio" "02. Issue" "03. Tax Lot" "04. Quantity" "05. Trade Price" "06a. Trade Date" "06b. Settlement Date" "07. Commission" "08. Other Transaction Expenses" "09. FX Rate" "10. Transtype (Credit)" "11. Transtype (Debit)"

Public Sub Application_BeforeTransaction(JEIndex As Long, TXIndex As Long) Dim dblQty As Double Dim dblPrice As Double Dim dblCommission As Double Dim dblOther As Double Dim dblFXRate As Double Dim dblAbsCostBasis As Double Dim dblAbsDiscPerc As Double Dim dblCalcAmount As Double Application.Context.AmountScale = 2 Application.Context.LEAmountScale = 2 Application.Context.QuantityScale = 2 ' Set the Deal, Position, and Deal Currency based on the selected LE and Issue SetDealAttributes ' set to no alloc for now and fix in AfterTransaction Application.Context.AllocationRule = cstAR_NoAllocation

43

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

' Retrieve parameters for calculation dblCommission = Application.Context.Value(cstParamCommission) dblOther = Application.Context.Value(cstParamOther) dblAbsCostBasis = Abs(Round(dblCommission + dblOther, Application.Context.AmountScale)) dblFXRate = Application.Context.Value(cstParamFXRate) dblQty = Application.Context.Quantity dblPrice = Application.Context.Value(cstParamTradePrice) dblCalcAmount = Round((dblQty * dblPrice) - dblAbsCostBasis, Application.Context.AmountScale) dblAbsDiscPerc = Round(1 - (dblCalcAmount/(dblPrice * dblQty)), 7) ' store cost basis & discount percentage Application.Context.CostBasisAmount = dblAbsCostBasis Application.Context.Value("Discount Percentage") = dblAbsDiscPerc ' Calculate Amount based on whether it's a credit or debit If TXIndex = 1 Then ' Debit JE Application.Context.Amount = -(dblCalcAmount) Application.Context.LEAmount = - (dblCalcAmount * dblFXRate) Else ' Credit JE Application.Context.Amount = (dblCalcAmount) Application.Context.LEAmount = (dblCalcAmount * dblFXRate) End If ' Round Amounts Application.Context.Amount = Round(Application.Context.Amount, Application.Context.AmountScale) Application.Context.LEAmount = Round(Application.Context.LEAmount, Application.Context.LEAmountScale) End Sub

Between the BeforeTransaction and AfterTransaction events is where the Allocation Rule for our transaction is fired. In our example, we set the Allocation Rule to NoAllocation, so no allocation is done. In other examples, we could set the Allocation Rule to another rule by Allocation Rule ID. In still other cases, we set the Allocation Rule to UserDefined in the BeforeTransaction. In that case, the allocation to investors is done in the AfterTransaction event and the InvestorSet result is filled in.
Public Sub Application_AfterTransaction(JEIndex As Long, TXIndex As Long, Result As InvestorSet) If TXIndex = 1 Then ' Debit JE Application.Context.AllocationRule = cstAR_NoAllocation Else ' Credit JE Application.Context.AllocationRule = cstAR_NonDominant End If End Sub

44

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Auxiliary Reports Note that in our BeforeTransaction event above, we had a call to a user-defined procedure SetDealAttributes. The purpose of this procedure is to set the Deal, Position, and transaction currency of the resulting transactions based on the Legal Entity and company issue parameters. We use an auxiliary report to get this information:
'--Function to set the Deal's Attributes based on the Legal Entity & Company Issue Sub SetDealAttributes() Dim oRpt As RWReport On Error GoTo errHandler ' --Create Report, set parameter, and then run report Set oRpt = Application.Reports.Item(, cstATMFolder, cstRptBuyATDealAttr) oRpt.Parameter("LEID") = Application.Context.LegalEntity oRpt.Parameter("CompanyIssueID") = Application.Context.Value(cstParamIssue) oRpt.Run '-- Get desired Value If oRpt.Rows = 1 Then ' rpt should only return one row with three columns Application.Context.Deal = CLng(oRpt.Cell(1, 1)) Application.Context.Position = CLng(oRpt.Cell(1, 2)) Application.Context.TransactionCurrency = CLng(oRpt.Cell(1, 3)) ElseIf oRpt.Rows = 0 Then Err.Raise vbObjectError + 6002, "AT: SetDealAttributes", _ "No data found in " & cstRptBuyATDealAttr & " report." & vbCrLf & _ "No information was found for the given Deal." Else Err.Raise vbObjectError + 6003, "AT: SetDealAttributes", _ "No data found in " & cstRptBuyATDealAttr & " report." & vbCrLf & _ "More than one row was found for the given Deal." End If errHandler: '-- Release oRpt From Memory Set oRpt = Nothing '--Raise error if any If Err.Number <> 0 Then Err.Raise Err.Number, Err.Source, Err.Description End Sub

45

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

In order to use an auxiliary report, we must first add a reference to it in the Active Template. Either right-click on the Auxiliary Reports node or use the menu item to find the report. Note that the auxiliary report must have already been created in the Investran Report Wizard. For more information on accessing and running reports in code, see the document The Developers Guide to Report Wizard Components.

Active Template with Driver Report

In the first example, our AT created one set of transactions based on the defined Journal Entry/Transaction tree. Usually though, we want to create a set of transactions for each record that meets certain criteria. For example, create an unrealized gain/loss transaction for each Deal/Position in a Legal Entity whose value changed during the last quarter or reverse and re-allocate each distribution during a given period according to investors capital balance at the end of the period. The concept of reversing and then re-allocating transactions according to a different rule is a common use for ATs and the purpose of our next example. In this AT Fiscal Period Allocation, our driver report retrieves all transactions for a given period for a Legal Entity. Each row of the driver report will create two separate transactions in different journal entries. The first transaction reverses the transaction selected by the driver report, assuming that transactions in this database are all initially entered with No Allocation. The second transaction will then rebook and reallocate this transaction to investors by an Allocation Rule called ByOpeningCapBalance.

46

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Create AT and Set Attributes These steps are the same as for the no driver report example.

Define Journal Entries/Transactions Journal entries and transaction templates are defined as before. The important thing to remember at this point is that this provides a template in which each row of the driver report will create transactions. Each row of the driver will create the transactions defined (although a transaction for a given row of the report can be eliminated by setting all values to 0).

47

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

In this example, we create two journal entries. One will contain the reversal transactions and one will contain the rebooked transactions. One reversal and one rebook transaction will be created for each row of the driver report.

Define Parameters Parameters are also defined as before. Some of the AT parameters, though, will be passed to the driver report automatically by the ATM Engine. It is important when defining the upper level AT parameters, to insure that those that are going to be passed to the driver report have the exact same name as the driver report parameters. In this example, note that the AT parameters End Date, LEID, and Start Date have the exact same names as the driver report parameters.

Define and Configure the Driver Report Driver reports, like all other reports, are created in the Investran Report Wizard. Driver reports must follow certain guidelines primarily, each (non-hidden) column of the results must be mappable to a property of the transaction (through the Application.Context object). The driver report is attached to the AT by right-clicking on the Driver Reports hierarchy node or using the Driver Reports menu.

48

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Once the driver report has been added, you will be able to view the parameters and columns of the report. The parameters must match parameters of the AT. The next step is to map the columns to properties of the Context object. To do so, select the Driver Reports node in the hierarchy tree.

Each visible column of the report must map to a property in the Context object logical defaults will already be chosen for you. You must also select a level at which these mappings will take place. For example, numeric amounts must always be at the Transaction Template level, because each row of the driver report will create new transactions. However, a Deal column could be at the transaction, journal entry, or batch level, depending on whether you want different Deals to: be all together in the same journal entry (transaction level); be in different journal entries but the same batch (journal entry level); or to actually create new batches each time the Deal changes (batch level). Note that for numeric columns, you must also choose which of the transaction templates you want these columns to map to (second half of Map to Property column). This would give you the opportunity for example, to include an amount column in the report and a negative amount column in the report, mapping one to the reversal transaction and one to the rebook transaction. In our example, though, we select only one set of amounts for all transactions and negate the values as necessary in code. Add VBA Code Adding VBA code is done as in our previous example. However, here it is important to keep in mind that the events are being fired multiple times, for different rows of our report.

49

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

In our example, because the driver report only contains the Legal Entity column at the batch level, and because Legal Entity is a mandatory parameter of our AT insuring that the report only contains one Legal Entity, BeforeBatch and BeforeJournalEntry events will only be fired at the beginning of the AT for the first row of the driver report (although BeforeJournalEntry will be fired twice at that time, once for each JE in the template). The BeforeBatch event is shown below.
Public Sub Application_BeforeBatch() ' reset variables Set mInvSetAlloc = Nothing mDrvRptCurrRow = 0 mDrvRptRowCount = GetDriverRptRowCount End Sub

Note: The code above uses another procedure (not shown) GetDriverRptRowCount to retrieve the total number of rows in the driver. This procedure calls and opens the driver report again as an auxiliary report and gets the RowCount. However, you can also access the number of rows in the driver report directly through the Application.Context.DriverReportRecordCount property. The BeforeTransaction and AfterTransaction events, though, will be fired for each row of the driver report. In addition, each row will fire each of these events twice, once for the Reversal JE/TT and once for the Fiscal Period Allocation JE/TT. Note that in the code below on the first call of this event for each row, we negate the amounts and set the allocation to NoAllocation, to reverse the entries retrieved by the driver report. In the second call of this event for each row, we keep the amounts positive but change the allocation to ByOpeningCapAcct to rebook the transaction with the new allocation.
Public Sub Application_BeforeTransaction(JEIndex As Long, TXIndex As Long) Application.Context.EffectiveDate = Application.Context.GLDate Application.Context.TransactionCurrency = GetCurrencyID(Application.Context.Deal, Application.Context.LegalEntity) Application.Context.AmountScale = 2 Application.Context.LEAmountScale = 2 Application.Context.QuantityScale = 2 If JEIndex = 1 Then ' Reverse JE ' Keep track of what row we're processing mDrvRptCurrRow = mDrvRptCurrRow + 1 Application.Context.AllocationRule = cstAR_NoAllocation ' do the reversal manually Application.Context.Amount = - (Application.Context.Amount) Application.Context.LEAmount = - (Application.Context.LEAmount) Else ' Fiscal Period Allocation JE so use the ByOpeningCapAcct Alloc Rule Application.Context.AllocationRule = cstAR_ByOpeningCapAcct End If End Sub

50

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

The AfterTransaction event below sets the last row to the non-dominant transaction. This is possible because we know the sum of the rows from our driver report balance to zero. In many cases, this is not possible and you must keep running totals in order to create the balancing non-dominant transaction.
Public Sub Application_AfterTransaction(JEIndex As Long, TXIndex As Long, Result As InvestorSet) If (mDrvRptCurrRow = mDrvRptRowCount) Then ' The last transaction in each JE will be the Non-Dom Application.Context.AllocationRule = cstAR_NonDominant End If End Sub

Note: The above AfterTransaction code has been simplified for illustration purposes. In the real version, additional code must be done in the rebook JE to rebalance the investor set of the non-dominant transaction due to rounding differences caused by the ByOpeningCapAcct Allocation Rule.

51

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Chapter

5
5. Active Template Development
This section provides information that may assist the Active Template Developer in constructing and troubleshooting new templates.

Active Template Development Tips

All reports used by Active Templates should be in Public Read-only report folders. User Defined Fields should be used to store values that would otherwise be hard coded within the VBA Code for an Active Template (such as Carry Percentage). The values for UDFs may be retrieved using Report Wizard reports.

Perform a Refresh operation in ATM whenever changes are made to reports that are used or will be used by an Active Template in development. Active templates in Draft status are not available for use in Investran. A templates status should be changed to Normal once it has been thoroughly tested in ATM. The ARM & ATM Export-Import Console application is a utility distributed with Investran that facilitates the transfer of Active Templates and related reports from one database to another. The following option is recommended as the first line in any Active Templates VBA, in order to explicitly require a variables declaration before use, and thus minimizing errors due to the accidental misspelling of a variable name.
Option Explicit

The following constants define some of the most commonly used system Allocation Rule numbers. Add additional constants for any other known system or user-defined Allocation Rule IDs. There is also Investran metadata available so that you can define reports to retrieve Allocation Rule IDs by name.
Private Const cstAR_NonDominant Private Const cstAR_NoAllocation Private Const cstAR_UserProvided As Long = 0 As Long = 1 As Long = 2

52

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

The journal entries generated by the AT must follow these standard Investran rules or the AT execution will fail: o o o A journal entry can contain only allocated or non-allocated transactions, not both. All investor allocations within a single transaction must have the same sign. Non-memo transactions must balance to zero within a journal entry. If multi-currency journal entries are not allowed (where AllowMultiCcyMemoJE in the Inv_SysConfiguration table is set to 0), then the balancing non-dominant transaction (created explicitly or by the ATM Engine) should balance the local amount and the amount in the Legal Entity currency. If multi-currency journal entries are permitted (where AllowMultiCcyMemoJE in the Inv_SysConfiguration table is set to 1 or 2), then the balancing non-dominant transaction should only balance the amount in the Legal Entity currency.

References to registered components may be added through the VBA Code window. Right-click on the VBA code and then select References from the Edit menu to bring up a list of available registered components.

53

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Chapter

6
6. Debugging Active Templates
Active Template Manager provides the VBA source level debugger for debugging the Active Template code. A debug log is also provided for logging debug messages and verifying the results of your code. The mode used for initial debugging of an Active Template is called simulation mode. In this mode, no transaction data is written to the Staging database or the Investran database. All operations will be carried out in memory, so it is safe to try any combination of values without fear of affecting the Investran data. Once an Active Template has been debugged and successfully run in simulation mode, the developer will change its status to Normal, so that it can be run using the regular Active Template execution process (see next chapter). Note that even at that time, additional testing will likely be performed to verify the Active Template results. Active Templates can be run and results output to the Staging database, without committing to the Investran database.

VBA Source Debugging

After the VBA coding has been completed, you should check that the code completes the tasks it was written to perform correctly. The first step of debugging involves detecting if there are syntactic errors, such as misspelled instructions, undeclared variables, missing control loops statements, and so on. To accomplish this, you should first try to execute the VBA code by clicking on the Run icon, in the VBA code window, marked by a green triangle.

The Run icon of the VBA window attempts to start the Active Template in simulation mode. Alternatively, you can use the Simulate icon or menu item available on the main ATM window. The first step the VBA interpreter does is syntax checking. If there are syntax errors, undeclared variables, or missing block control statements, ATM will display the offending line in red, and a brief description of the error will appear in the VBA code window status area. Once you identify the line that is causing the compile error, you can click on the Parameters Dialog box exit button and return to the VBA code window to fix it.

54

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Note: The error message displayed may not always be clear in describing exactly what is wrong with your code. Whenever you get an error message that reads, Expecting an existing scalar var, check for undefined variables, undefined constants, or incorrect types passed as parameters.

55

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

As a rule of thumb, you can tell if your VBA code compiles correctly if after clicking on the Run button you can see the Immediate window behind the parameters dialog box.

Once you see the Immediate window in the back, you know that your VBA code is free of syntax errors. Now it is time to debug the logic of your program. To accomplish this, you can set breakpoints in the code - in much the same way you do in todays most popular languages. Click on the gutter area next to the instruction where you want the execution to stop and a red line will appear, indicating that a breakpoint has been set.

56

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Once a breakpoint has been set, use the run icon to execute the code up to this breakpoint. You can also step through lines of code using the Step Over, Step Into, and Step Out functions. A yellow line indicates the next source line to be executed. You can also use the immediate window to execute short VBA statements, or to see the current values of certain variables you are interested in.

57

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

The watch window and the stack window work similarly to their counterparts in Microsoft Visual Basic. The watch window provides a means to keep a watch on specified variable values as lines of code are executed. The stack tab provides a window into the run-time stack.

The following table describes the most important functions that are available from the VBA code window toolbar and that allow the developer control the execution flow according to his or her needs.
Button Description Executes the VBA code. If the AT has any parameters, the parameters dialog box is displayed and all the code is executed. Temporarily suspends execution of the VBA code. To resume, you may click the Run button. Stops all execution of the VBA code and the results window is displayed. Execution of the VBA code cannot be resumed once stopped. It must be restarted. Sets a breakpoint in the line where the cursor is. The same effect can be achieved by clicking in the gutter area next to the statement where a breakpoint is desired. Evaluates the currently selected expression and display the results in the immediate window. Scroll the VBA code window so the current statement is displayed. Executes the code line by line and enters into the body of subroutines and functions. Executes the code line by line but does not enter into the Subroutine or Functions code. Treats the call statement as a single line of code. Executes the remaining sub or function code and exists the subroutine or function code at once.

Run Pause Stop Breakpoint Evaluate Current Statement Step Into Step Over Step Out

58

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Debug Log
Active Template Manager also provides a built-in debugging log that can be used in simulation mode. The log displays after an Active Template execution in simulation mode. It contains the steps performed in the execution, along with the data it would be writing to the Staging databases transaction tables. In particular, it shows the transactions created and the investor allocations.

The ATM object model also provides a mean for you to write to the debugging log from within your VBA code. You can write any debugging messages to the code using the Log method of the Application object.
Application.Log Amount to be allocated is & CStr(Application.Context.Amount)

59

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Chapter

7
7. Executing Active Templates
Required Conditions
Once an Active Template has been properly debugged and checked for logic errors in simulation mode, it should be executed using the ATM scheduler engine to make sure it is ready for production. The results of theses test AT executions can be deleted from the Staging database without committing to Investran, or they can even be committed and later deleted through the Transaction panel. To execute an Active Template using the ATM scheduler engine, the Scheduler Service must have been properly installed and configured. The Staging and Investran databases must be properly configured in order for the Scheduler process to properly commit the results to the Investran database. The installation and configuration of the ATM scheduler service fall out of the scope of this document. However, these are some of the key points that the ATM developer may check with the Database and Investran Administrators in case of troubles: 1. Make sure the user selected to run the Scheduler Service meets the following requirements: a. Belongs to the SQL Administrators Group in the Master (Investran) database.

b. Is the Database Owner (DBO) of the Staging database. c. Belongs to the Investran Administrators Group (ISM Permissions).

2. Connect to the Master (Investran) database and make sure that: a. The field UseATM in the App_Customize table is set to Yes.

b. The field IsMaster in the App_Customize table is set to Yes. c. The field StagingConnection in the App_Customize table contains the complete ADO connection string to connect to the Staging database, in a format similar to the following "server=STAGING_SRVR_NAME;database=STAGING_DB_NAME;driver={SQL Server}". Of course, the connection string will depend on whether youll be using SQL or NT authentication.

60

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

3. Connect to the Staging Database and make sure that: a. The Field MasterServer in the App_Customize table has the name of the server where the Investran database resides (only the name).

b. The field MasterDatabase in the App_Customize table has the name of the Investran database (only the name).

Executing the Active Template

The Active Template can be started from two different places: from the Investran Application, and from the Active Template Manager. This section Deals only with how to execute an Active Template from the Active Template Manager. To start the scheduling process of the execution of an Active Template, first select the Active Template to execute from the tree on the left panel of the Active Template Manager. Make sure that the Active Template box has the name of the Active Template you intend to run, and click the icon.

This should pop up a dialog box that contains the AT run-time parameters (if any) and some of the AT properties that can be configured in this box. The dialog box initially shows the Common Input Values tab where the user can select and type in the values for the required run-time parameters. To select a parameter, just click on the desired parameter and a list box that appears on the lower left corner of the dialog box will be enabled so the user can either pick up a selection value or key in an appropriate one, depending of the characteristics of the parameter.

61

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

There is also a check box on the right side named Show values in controlled context that when checked, will only allow the Parameter Value list box display values that make sense according to previously selected parameter values. For example, if an Active Template requires Both Legal Entity and Deal as parameters, if the Legal Entity has already been selected, and the Show values in controlled context box is checked, then when selecting the Deal, only those Deals related to the previously selected Legal Entity will be displayed for selection. If check off, all Deals will be displayed, regardless if they belong or not to the previously selected Legal Entity.

When all the required parameters have been populated, the AT is ready to be scheduled. Notice that this document refers to the process as scheduling for execution as opposed to executing. This is because the execution of the AT is not carried out right away after you press the execution button, instead, it is scheduled to be executed at a later time. Of course, you can schedule the process to be executed immediately. Note: The ATM scheduling process does not allow the scheduling of an AT to be run more than once.

62

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

To schedule the AT to be executed, you should click on the button marked as that appears in the toolbar located of the left side of the dialog box, this will display the AT Scheduling Options dialog box.

The AT Scheduling Options dialog box contains two sections, with several options in each one. The first section deals with the date and time at which the AT will be executed. You can select the Run AT at option and specify a date and time when you want the AT to be processed. You can select, for example, to run the AT at night, when there is less demand on the database server, or at a future date, when all the data required for the AT to run will be already present in the database. You may also choose to run the AT immediately. This means that the process will be scheduled to be run as soon as the next time the scheduler service checks for pending tasks. As explained before, the AT execution process is divided in two stages: the Batch Generation process and the Commit process. The Batch Generation process occurs in a special database called the Staging database. It allows you to review the batches and if you are happy with the results, you can then commit them to the Investran database. The second group of options deals with this process. The option Commit process without showing results will automatically commit the results to the Investran database without letting you revise them. In order to see the results, you must open Investran and check the Transaction panel. You can set the ATM engine to commit the results immediately after the batch generation has finished or at a certain time in the future. The safest option to use while in development is, Show temporary results Preview. This option allows the user to see all transactions and allocations and commit the results after they have been examined.

63

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

AT Execution Maintenance
Because the AT execution process runs asynchronously, the AT Manager provides a simple way to check the status of the AT: Batch Generation process, Commit process and Process Notification.

The Batch Generation Maintenance Process, marked as in the ATM toolbar, allows the user to check the status of the Batch Generation process. When you select this option, a box is displayed with all the Active Templates that have been queued for processing and their status. Possible statuses are: Pending: The AT has been queued but the engine hasnt started the execution. Running: The AT is being processed. Cancelled: The AT has been cancelled by the user.

You can click the refresh button (

) to see what the status of the AT is at the moment.

64

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Once the Batch Generation process is complete, the task identified by the Process ID is moved to the Generated tab whether the task completed successfully or not. If the AT that has been scheduled does not appears in the Pending tab list, then it has already been processed and should appear in the Generated tab.

The generated tab contains information regarding the time it took for the engine to execute the AT and the result of that process. The last column, marked as Succeeded will contain the checked check box if the AT generated at least one batch, and a blank box if for some reason, the AT did not generate any batch. This may or may not be an error, as it may be possible for one AT, under certain circumstances, not to generate any transaction.

65

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

You can tell if there were errors during the execution of the AT by checking the execution log file. The log file can be retrieved by right-clicking on the process ID that you would like to check and selecting View Log from the context popup menu, or by using the keyboard shortcut CTRL+L

The log file will then tell you what went wrong during the execution of an AT, as the following screenshot shows.

If the generation process concluded successfully, then you can review the result by invoking the context menu and selecting Preview, or by hitting CTRL+P after selecting the desired process ID. A window resembling the Investran Transaction panel will pop up allowing you to check the batches that were generated by the AT. If you are satisfied with the results, you can then tell ATM that you want to commit the batches to the Investran database. You can do that by clicking on the icon that appears on the toolbar of the preview window, or directly from the context pop-up menu, by selecting Schedule (CTRL + R). The Commit maintenance screen, which can be invoked from the ATM toolbar by clicking on the button, provides basically the same functionality that the Batch Generation screen does, but only for the Commit process. Another difference is that it does not provide a Preview window. The last option is the Process notification ( ). This option instructs the system to notify you when certain events occur during the AT processing, such as Generated Batches or Failed Batches amongst others.

66

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

When you click on Process Notification the Notification Settings screen will be displayed.

This screen has two main options: 1. Check for Batches Generation when Login to Database. This option will allow you to run an AT and close the ATM application. Next time you log on to the Investran database, using any tool in the Investran suite, you will be notified of the results of the AT that you left running. 2. Check for batches generation. This option allows you to periodically (based on the frequency selected) be notified by the system with the results of the events you select, such as Batches generated, batches failed, and so on.

67

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Chapter

8
8. Appendix A: ATM Properties
The following table lists all of the ATM properties which can be accessed using this method along with their corresponding data type.
Property Account Allocation Rule Amount Amount Scale Amount Total Scale ATBoolean1 ATBoolean2 ATBoolean3 ATBoolean4 ATBoolean5 ATDate1 ATDate2 ATDate3 ATDate4 ATDate5 ATNumeric1 ATNumeric2 ATNumeric3 ATNumeric4 ATNumeric5 ATText1 Data Type Lookup Lookup Numeric Numeric Numeric Boolean Boolean Boolean Boolean Boolean Date Date Date Date Date Numeric Numeric Numeric Numeric Numeric Text

68

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Property ATText2 ATText3 ATText4 ATText5 ATText6 ATText7 ATText8 ATText9 ATText10 Batch Code Batch Description Batch Status BatchID Close to AcctID Deal Discount Percentage Effective Date Exchange Rate Expiration Date GL Date GL Ref1 Hedged Income Security IsDebit JE # JournalEntryTypeID LE Amount Scale Legal Entity Lot Memo

Data Type Text Text Text Text Text Text Text Text Text Text Text Lookup ID ID Lookup Numeric Date Numeric Date Date Text Boolean Lookup Boolean Text Lookup Numeric Lookup Lookup Boolean

69

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Property Non Dominant Account Non Dominant Deal Non Dominant GL Ref1 Non Dominant Income Security Non Dominant Lot Non Dominant PIK Income Security Non Dominant PoolNumber Non Dominant Position Non Dominant Transaction Comments Non Dominant UserDefined Date1 Non Dominant UserDefinedD1 Non Dominant UserDefinedLookup1 Non Dominant UserDefinedLookup2 PIK Income Security Pool Position QA Text Quantity Quantity Scale Quantity Total Scale SettlementDate Transaction Comments Transaction Currency

Data Type Lookup Lookup Text Lookup Lookup Lookup Lookup Lookup Text Date ID Lookup Lookup ID Lookup Lookup Text Numeric Numeric Numeric Date Text Lookup

70

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Property Transaction Type (Credit) Transaction Type (Debit) Transaction Type Non-Dominant (Credit) Transaction Type Non-Dominant (Debit) TransID User Defined Numeric UserDefinedDate1 UserDefinedD1 UserDefinedLookup1 UserDefinedLookup2

Data Type Lookup Lookup Lookup Lookup ID Numeric Date ID Lookup Lookup

71

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Chapter

9
Appendix B: Troubleshooting
Error Error creating transaction: Multiple-step operation generated errors. ATM execution failed. Overflow. Explanation This issue occurs if the AT has an auxiliary report that uses Boolean values.

The report will handle Boolean values correctly if the FetchBoolean property is set to True in the AT code.
This issue occurs when the number of calls to the BeforeCommitSQLCommands event or AfterCommitedSQLCommands event is greater than 32,766 for any given process.

When this issue occurs, try to reduce the total number of SQL commands inserted by the process. For instance, if the issue occurs when the Deal Name parameter is disabled, specify a value for the Deal Name parameter to reduce the total number of SQL commands inserted by the process.
Multiple-step operation generated errors. Check each status value. This issue occurs when the internal value for a driver report row is an empty string () instead of the Null value. To be interpreted correctly by the ATM engine, the internal value for empty driver report rows must be Null.

To resolve this issue, include the following procedure in the VBA code and call it at the end of the Application_BeforeTransaction event:
Public Sub FixingContext() If (Application.Context.ExpirationDate = "") Then Application.Context.ExpirationDate = Null If (Application.Context.PIKCompanySubIssue = "") Then Application.Context.PIKCompanySubIssue = Null End Sub

72

D E V E L O P E R S

G U I D E

T O

A C T I V E

T E M P L A T E

M A N A G E R

Error A Batch for a GP LE where the transaction is not in Draft status and the allocation rule is not "No Allocation" or "Non-Dominant", the total transaction amount was allocated with NULL value for all Investor IDs.

Explanation This issue occurs when the Application_AfterTransaction event is used to allocate a dominant transaction with an Allocation Rule other than No Allocation for a GP Legal Entity.

To troubleshoot, use the AT Simulation mode and set a break point in the VBA code associated with the Application_AfterTransaction event to determine if there is an instance where the event is allocating the amount from the unallocated investor (the first in the investor set). The code should be updated to allocate the amount from the investors associated with the GP Legal Entity.
This issue may occur when the driver report returns more rows when it is run in ATM than when it is run in Report Wizard using the same parameters.

ATM execution failed. Row index [#] out of range [1 - #].

To troubleshoot this issue, review the data retrieved by the driver report to determine why it is returning a greater number of rows when run in ATM as opposed to Report Wizard.

73

www.sungard.com/investran/learnmore

SunGard Investran 1801 NE 123rd Street Suite 400 Miami, FL 33181 Tel: 305-892-3200

Trademark Information: SunGard, the SunGard logo, Investran Accounting, Investran CRM , and SunGard DX are trademarks or registered trademarks of SunGard Data Systems, Inc. or its subsidiaries in the U.S. and other countries. All other trade names are trademarks or registered trademarks of their respective holders.

2011 SunGard