Import File and Related Events
Import File Definition & Attributes
Data is stored in TallyPrime as objects, and they are categorized as Masters and Vouchers/Transactions. This data in TallyPrime can be exchanged with external applications, i.e. Masters and Vouchers can be imported into TallyPrime and also exported out of TallyPrime. Whenever data (in XML, JSON or Excel format) is directly imported into TallyPrime, while the platform does all the checks to ensure the schema validations and business logics, some flexibilities are exposed in TDL with the view of integration to make some modifications of data possible during import process. For example, converting sales vouchers into purchase vouchers during import. These TDL capabilities are used when one wants to use the default natively available import facility of TallyPrime but wants to make some minor adjustments to the data before it is pushed into the company.
This is done with the help of the definition ‘Import File’. Default TDL already has 2 Import file definitions ‘All Masters’ and ‘Vouchers’, which gets called during Master import and voucher import respectively. As per where the changes are required, the respective import file definition is modified and then with the help of the attributes the changes required are made. For Example, to convert sales voucher into purchase in TallyPrime during import, one would modify the Import File definition ‘Vouchers’ and add respective code to change the voucher type from sales to purchase.
Snapshots of Import File definitions of All Masters and Vouchers from default TDL of TallyPrime Release 7.0.
Response Report
During online integration with TallyPrime which can happen in JSON or XML formats, masters and Vouchers can be pushed to Tally directly if the structure of the data is in the native format. When the data gets pushed to TallyPrime from external application, a response is sent back to the requesting client by default in JSON or XML format as per the request format, giving details on the import statuses. In order to send a custom response instead of the default one, the attribute Response Report is used.
Syntax
Response Report:<Report Name>
Where,
<Report Name> is the Name of the Report definition which is used to construct the response XML or JSON.
Example
In this example, the import file ‘All Masters’ is modified, and a response report is added which generates a custom response for any Request. When the request is in JSON format, the response is also constructed in JSON format. When the request is in XML format, the same report can be used to construct the XML response (Since XML Tag and JSON Tag are aliases to each other)
[#Import File: All Masters]
Option : TSPL Smp Custom Response Report
[!Import File: TSPL Smp Custom Response Report]
Response Report : TSPL Smp ResponseRpt
;; Response Report
[Report: TSPL Smp ResponseRpt]
…
…
[Line: TSPL Smp ResponseRpt]
Fields : TSPL Smp ImportType, TSPL Smp LastImportError
XMLTag : “Custom Response Line”
Explode : TSPL Smp ImportInfo
Explode : TSPL Smp HTTPInfo
[Field: TSPL Smp ImportType]
Set as : $$ImportType
XMLTag: “Import Type”
[Field: TSPL Smp LastImportError]
Set as : $$LastImportError
XMLTag : “LastImportError”
[Part: TSPL Smp ImportInfo]
Lines : TSPL Smp ImportInfo
[Line: TSPL Smp ImportInfo]
Fields : TSPL Smp ImportInfoCreated, TSPL Smp ImportInfoAltered, TSPL Smp ImportInfoCombined
Fields : TSPL Smp ImportInfoIgnored, TSPL Smp ImportInfoErrors
XMLTag : “ImportInfo”
[Field: TSPL Smp ImportInfoCreated]
Set as : $$ImportInfo:Created
XMLTag: “Created”
[Field: TSPL Smp ImportInfoAltered]
Set as : $$ImportInfo:Altered
XMLTag: “Altered”
[Field: TSPL Smp ImportInfoCombined]
Set as : $$ImportInfo:Combined
XMLTag: “Combined”
[Field: TSPL Smp ImportInfoIgnored]
Set as : $$ImportInfo:Ignored
XMLTag: “Ignored”
[Field: TSPL Smp ImportInfoErrors]
Set as : $$ImportInfo:Errors
XMLTag: “Errors”
[Part: TSPL Smp HTTPInfo]
Use : TSPL Smp ImportInfo
Local : Line : TSPL Smp ImportInfo: XMLTag: “HTTPInfo”
Local : Field : TSPL Smp ImportInfoCreated : Set as : $$HTTPInfo:URL
Local : Field : TSPL Smp ImportInfoCreated: XMLTag: “URL”
Local : Field : TSPL Smp ImportInfoAltered: Set as: $$HTTPInfo:HEADER:Connection
Local : Field : TSPL Smp ImportInfoAltered: XMLTag: “HeaderConnection”
Local : Field : TSPL Smp ImportInfoCombined : Set as: $$HTTPInfo:HEADER:Unicode
Local : Field : TSPL Smp ImportInfoCombined : XMLTag : “Unicode”
Local : Field : TSPL Smp ImportInfoIgnored: Set as: $$HTTPInfo:HEADER:ContentType
Local : Field : TSPL Smp ImportInfoIgnored: XMLTag: “HeaderContentType”
Local : Field : TSPL Smp ImportInfoErrors: Set as: $$HTTPInfo:ContentLength
Local : Field : TSPL Smp ImportInfoErrors: XMLTag: “ContentLength”
|
JSON Request |
Default Response (Without Response Report) |
Custom Response (With Response Report) |
|
content-type:application/json version: 1 tallyrequest: Import type: Data id: All Masters
{ “static_variables”: [ { “name”: “svMstImportFormat”, “value”: “jsonex” }, { “name”: “svCurrentCompany”, “value”: “Bhrama Enterprises” } ], “tallymessage”: [ { “metadata”: { “type”: “Ledger”, “action”: “create”, “name”: “Bank Of Baroda” }, “name”: “Bank Of Baroda”, “parent”: “Bank Accounts” } ] } |
{ “status”: “1”, “data”: { “import_result”: { “created”: 0, “altered”: 1, “deleted”: 0, “lastvchid”: 0, “lastmid”: 0, “combined”: 0, “ignored”: 0, “errors”: 0, “cancelled”: 0, “exceptions”: 0 } } } |
{ “Custom Response Part”: { “Custom Response Line”: { “Import Type”: “SOAP”, “tsplsmpimportinfo”: { “ImportInfo”: { “Created”: “0”, “Altered”: “1”, “Combined”: “0”, “Ignored”: “0”, “Errors”: “0” } }, “tsplsmphttpinfo”: { “HTTPInfo”: { “URL”: “/”, “HeaderConnection”: “Keep-Alive”, “Unicode”: “YES”, “HeaderContentType”: “application/json”, “ContentLength”: “1040” } } } } } |
Empty
Data, i.e. masters and vouchers in native JSON or XML format or in mapped excel can be directly imported in TallyPrime. During the import, if one wants to discard a particular object from importing then this attribute can be used. The records that satisfy the condition will not be imported.
Syntax
Empty: <Logical Expression>
Where,
<Logical Expression>: Expression that evaluates to a logical value
Example
Here, The Import File Vouchers is modified to discard all the Payment vouchers from the import data if the data is in JSON Format.
[#Import File: Vouchers]
Option : TSPL Empty Payments : @@IsJSONImpFormat
[!Import File: TSPL Empty Payments]
Empty : $$IsPayment:$VoucherTypeName
Import File Events
Data, i.e. masters and vouchers in native JSON or XML format or in mapped excel can be directly imported in TallyPrime. When data is imported (offline or online) into TallyPrime one might want to create appropriate logs, modify values in the objects imported, or track changes and record it to construct a response after the import process ends or terminate the import process on some condition. All of this can be accomplished with the help of the Import File events Start Import, Import Object, After import Object and End Import
Start Import
This event is called when the import process starts. Common use cases are to update logs or show a message box saying the import process is starting.
Syntax
On: Start Import: <Logical Condition Expr> :<Action Keyword> :<Action Parameters>
Where,
<Logical Condition Expr> is a Logical Expression, which when evaluates to TRUE, executes the given Action.
<Action Keyword> is the Action to be taken once the System Event is triggered.
<Action Parameters> are the parameters required for the given Action.
This event is not applicable, when masters and vouchers are imported via HTTP Request.
Import Object
This allows the TDL programmer to take desired action during the import of the object. Common use cases are to modify the values of the methods of the object during import.
Syntax
On: Import Object: <Logical Condition Expr> :<Action Keyword> :<Action Parameters>
Where,
<Logical Condition Expr> is a Logical Expression, which when evaluates to TRUE, executes the given Action.
<Action Keyword> is the Action to be taken once the System Event is triggered.
<Action Parameters> are the parameters required for the given Action.
When this event is used, the statement ‘On : Import Object: <condition>:Import Object’ statement should be written because, when the system is directed to do a different action on import of object, once the action statements are written, it also needs to be intimated to complete the import of the object.
This event is not applicable, when masters and vouchers are imported via HTTP Request.
After Import Object
This allows the TDL Programmer to take any desired action every time an Object is imported. This Event will help the user to create appropriate logs after Importing of each Object, terminate the Import Process based on some condition, track/record changes that can be used for preparing the response (for SOAP requests), etc.
Syntax
On: After Import Object: <Logical Condition Expr> :<Action Keyword> :<Action Parameters>
Where,
<Logical Condition Expr> is a Logical Expression, which when evaluates to TRUE, executes the given Action.
<Action Keyword> is the Action to be taken once the System Event is triggered.
<Action Parameters> are the parameters required for the particular Action.
End Import
This event is called when the import process ends. Common use cases are to update logs or show a message box saying the import process is ending.
Syntax
On: End Import: <Logical Condition Expr> :<Action Keyword> :<Action Parameters>
Where,
<Logical Condition Expr> is a Logical Expression, which when evaluates to TRUE, executes the given Action.
<Action Keyword> is the Action to be taken once the System Event is triggered.
<Action Parameters> are the parameters required for the given Action.
This event is not applicable, when masters and vouchers are imported via HTTP Request.
Example: Import File Events
Here the import process is initiated with the ‘Import’ action that takes the parameter ‘Vouchers’, thus invoking the import file Vouchers. The data from the Receipt.xml file is imported and the following happens
- On:Start Import: When the import starts, a message box saying Import is starting is given
- On:Import Object : When each voucher object gets imported, If its receipt voucher then its changed to Payment and Narration is also updated
- On: After import Object: After the Import of each object, details of the import is logged with the platform function $$ImportAction(indicate the status of Import, i.e., whether the current Object was Created, Altered, etc), $$LastImportError (Import error description for the last object imported), $$ImportType(type of Import, i.e., the source of data)
- On:End Import: When the import Ends, a message box saying Import is completed is given
[Function: TSPL Smp ImportVouchers]
Variable : Import File : String
10: MSGBOX : “Import Vouchers” : “This will convert all Receipt Vouchers as Payment while Importing the Vouchers”
20: SET : Import File : “.\XMLData\Receipt.XML”
30 : SET : TSPL Smp Import Flag : YES
40: IMPORT : Vouchers
50 : SET : TSPL Smp Import Flag : NO
[#Import File: Vouchers]
;; Actions with ‘Start Import’ Events get executed prior to starting the Import process
On : Start Import : ##TSPLSmpImportFlag : Call : TSPL Smp Start Import
;; Actions with ‘Import Object’ Events get executed during Importing the Object where
;; current Object context will be available for manipulation
On : Import Object : ##TSPLSmpImportFlag : Call : TSPL Smp Change Values
On : Import Object : ##TSPLSmpImportFlag : Import Object
;; This Event After Import Object is triggered for each Object
On : After Import Object : Yes : Call : TSPL Smp LogInfo : “After Import Object – ” + $$ImportAction + ” – ” + $$LastImportError + ” – ” + $$ImportType
;; Actions with ‘End Import’ Events get executed after Importing the Object
On : End Import : ##TSPLSmpImportFlag : Call : TSPL Smp End Import
[Function: TSPL Smp Start Import]
00 : MSGBOX : “Status” : “Import Started…”
[Function: TSPL Smp Change Values]
Local Formula : DateTimeUpdation : “Updated on ” + ($$String:@DateUpdation) + ” at ” + ($$SysInfo:SystemTime)
Local Formula : DateUpdation : $$SysInfo:SystemDate
;; Since current voucher context is available, Default External Voucher Method
;; ‘IsReceipt’ is available in this function context
00 : IF : $IsReceipt
10 : SET VALUE : VoucherTypeName : “Payment”
20 : SET VALUE : Narration : if $$IsEmpty:$Narration then @DateTimeUpdation else $Narration + ” – ” + @DateTimeUpdation
30 : ENDIF
[Function: TSPL Smp LogInfo]
Parameter : pLogInfo : String : “”
40 : Log : ##pLogInfo
[Function: TSPL Smp End Import]
00 : MSGBOX : “Status” : “Import Completed…”
