Upload
buituyen
View
298
Download
2
Embed Size (px)
Citation preview
ARGUS Developer Import Actuals Data
Import Actuals Data ARGUS Developer 7.1
December 4th, 2015
ARGUS Software – An Altus Group Company
ARGUS Developer Import Actuals Data
Import Actuals Data for ARGUS Developer 7.1 December 4th, 2015 Published by: ARGUS Software, Inc. 3050 Post Oak Boulevard Suite 900 Houston, Texas 77056 Telephone (713) 621-4343 Facsimile (713) 621-2787 www.argussoftware.com Information in this document is subject to change without notice and represents no commitment on the part of ARGUS Software, Inc. This document is copyright 2015, ARGUS Software, Inc. All rights reserved. This document is a confidential and proprietary trade secret of ARGUS Software, made available only under a license agreement and or other agreements containing obligations of confidentiality. "ARGUS" and “ARGUS Enterprise” are trademarks of ARGUS Software, Inc. All other trademarks and registered trademarks are property of their respective companies.
ARGUS Developer Import Actuals Data
Table of Contents
Purpose .......................................................................................................................................................................... 1
Project Data Sources...................................................................................................................................................... 2
Extensible Markup Language (.xml) Files .................................................................................................................. 2
Attribute Name and Transaction Type Table ............................................................................................................ 4
Comma Separated Value (.csv) Files ......................................................................................................................... 5
External Data Sources .................................................................................................................................................... 7
Opening the Configuration Manager ........................................................................................................................ 7
Creating a new Import Configuration ....................................................................................................................... 7
Import Actuals Data ..................................................................................................................................................... 10
Interactive Imports .................................................................................................................................................. 10
XML File Import ....................................................................................................................................................... 11
CSV File Import ........................................................................................................................................................ 11
External Data Source Import ................................................................................................................................... 12
Selecting the Projects to Import.............................................................................................................................. 12
Adding and replacing data in the database ............................................................................................................. 12
Unattended Updates ................................................................................................................................................... 13
Unattended Update Configurations ........................................................................................................................ 13
Actuals in XML Format ............................................................................................................................................ 13
Actuals in CSV Format ............................................................................................................................................. 13
External Data Source ............................................................................................................................................... 14
Windows Task Scheduler ........................................................................................................................................ 14
Logging the Result of an Unattended Update ......................................................................................................... 18
ARGUS Developer Import Actuals Data
1 © 2015 ARGUS Software, Inc.
Purpose
The purpose of this document is to provide a detailed instructions on importing Actuals Data using a variety of file
formats.
It is recommended that the setting up of the Actuals Data Import files and process be carried out by an IT
Administrator with strong knowledge of .xml files and external data sources.
If you have questions, please contact your ARGUS Account Manager, who can provide a list of Service options
available for the installation and implementation of ARGUS Developer.
ARGUS Developer Import Actuals Data
2 © 2015 ARGUS Software, Inc.
Project Data Sources
Extensible Markup Language (.xml) Files
File Format
An Actuals Import definition file is an XML file (a markup language that defines a set of rules for encoding
documents in a format that is both human-readable and machine-readable). It defines a number of source data
records to be imported into multiple projects in ARGUS Developer.
XML Schema Definition (.xsd)
The following specifies how to formally describe the elements in the Actuals Import .xml document. It is used to
verify that each item of content in the Actuals Import .xml file adheres to the description of the element in which
the content is to be placed. An example .xml file containing data is on page 5.
<?xml version="1.0"?> <xs:schema xmlns:argus="http://www.circlesoftware.com/database" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.circlesoftware.com/database"> <xs:element name="ExportAll"> <xs:complexType> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element name="TDevelopmentProject" type="argus:TDevelopmentProject"/> </xs:sequence> <xs:attribute name="Version" fixed="1.0.0.0"/> <xs:attribute name="TargetApplication" fixed="ArgusBudget"/> <xs:attribute name="ObjectCount" type="xs:positiveInteger"/> <xs:attribute name="By" type="xs:string"/> <xs:attribute name="Title" type="xs:string"/> <xs:attribute name="Note" type="xs:string"/> <xs:attribute name="Author" type="xs:string"/> </xs:complexType> </xs:element> <xs:complexType name="TSpreadsheetSourceData"> <xs:sequence minOccurs="0" maxOccurs="unbounded"> </xs:sequence> <xs:attribute name="Named" type="xs:string"/> <xs:attribute name="Description" type="xs:string"/> <xs:attribute name="AdditionalInfo" type="xs:string"/> <xs:attribute name="AccountingDate" type="xs:date"/> <xs:attribute name="TransactionDate" type="xs:date"/> <xs:attribute name="InvoiceNum" type="xs:string"/> <xs:attribute name="OriginalJobNumber" type="xs:string"/> <xs:attribute name="Amount" type="xs:double"/> <xs:attribute name="OriginalCode" type="xs:string"/> <xs:attribute name="MajorCode" type="xs:string"/> <xs:attribute name="MinorCode" type="xs:string"/> <xs:attribute name="SubCode1" type="xs:string"/> <xs:attribute name="SubCode2" type="xs:string"/> <xs:attribute name="SourceRef" type="xs:string"/> <xs:attribute name="DatabaseRef" type="xs:string"/>
ARGUS Developer Import Actuals Data
3 © 2015 ARGUS Software, Inc.
<xs:attribute name="Units" type="xs:integer"/> <xs:attribute name="RowDataType" type="xs:integer"/> </xs:complexType> <xs:complexType name="TDevelopmentProject"> <xs:all> <xs:element name="SourceDataRecords"> <xs:complexType> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element name="TSpreadsheetSourceData" type="argus:TSpreadsheetSourceData"/> </xs:sequence> </xs:complexType> </xs:element> </xs:all> </xs:complexType> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element name="Fields" type="argus:Fields"/> </xs:sequence> </xs:complexType> <xs:complexType name="Fields"> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element name="Field" type="argus:Field"/> </xs:sequence> </xs:complexType> <xs:complexType name="Field"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="Name" type="xs:string"/> </xs:extension> </xs:simpleContent> </xs:complexType> </xs:schema>
Schema Description
The root of the xml is the ExportAll element.
ExportAll
This is the root element type. This element describes the data being imported with the following details:
Attribute Name Description
Title The title of the data. Arbitrary string displayed to user during the import procedure.
Note Notes attached to the data. Arbitrary string displayed to user during the import procedure.
By The name of the application that created the data. Arbitrary string displayed to user during the import procedure.
Author The name of the author of the data. Arbitrary string displayed to user during the import procedure.
ObjectCount Optional count of the number of records in the XML. This is used to indicate to the user the number of records to be imported and is not required for the import procedure itself.
ARGUS Developer Import Actuals Data
4 © 2015 ARGUS Software, Inc.
TDevelopmentProject
This is the container element for all the individual records to be imported.
TSpreadsheetSourceData
The TSpreadsheetSourceData element type represents a single source data record.
Attribute Name and Transaction Type Table
Order Attribute Name Description Format Type (MSSQL)
Maximum Length
M/O *
1 AccountingDate The invoice date. Can be the same as the TransactionDate if you wish.
datetime N/a M
2 AdditionalInfo Any additional information (alpha-numeric) to be stored against this record.
nvarchar 240 O
3 Amount The invoice amount as input to the external system. float N/a M
4 Description The Supplier Name for this record. Can include accounting journal description.
nvarchar 150 O
5 InvoiceNum The invoice number (or other reference) of this record.
nvarchar 30 O
6 MajorCode The major code part of the cost code for this record. nvarchar 20 M
7 MinorCode The minor code part of the cost code for this record. nvarchar 20 M
8 Named Description of Cost Code nvarchar 50 O
9 OriginalJobNumber
The job number to match against the project being imported into. Only records with an original job number matching the project job number will be imported.
nvarchar 50 M
10 SubCode1 The first sub-code of the cost code for this record. nvarchar 20 O
11 Subcode2 The second sub-code of the cost code for this record. nvarchar 20 O
12 TransactionDate The date when the transaction is processed through your finance system (i.e. date paid).
datetime N/a M
13 TransactionType The type of transaction. nvarchar 50 O
14 Units The number of units in a residential development. int N/a O
15 OriginalCode This is the cost code displayed in full from your external data source.
nvarchar 50 O
16 RowDataType The RowDataType must be set to 3, to allow import of actuals.
nvarchar 20 M
17 SourceRef User defined reference id for 3rd party external system (e.g. Finance = FIN01, Sales = SAL01)
nvarchar 32 M
ARGUS Developer Import Actuals Data
5 © 2015 ARGUS Software, Inc.
Order Attribute Name Description Format Type (MSSQL)
Maximum Length
M/O *
18 DatabaseRef Unique database ID reference held for each transaction record in the external database (e.g audit trail unique reference id).
nvarchar 32 M
*M/O - Mandatory/Optional if importing actuals via a .csv or .xml format.
Example .xml File
<?xml version="1.0" encoding="UTF-8"?>
<circle:ExportAll xmlns:circle="http://www.circlesoftware.com/database"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.circlesoftware.com/database.xsd">
<TDevelopmentProject>
<SourceDataRecords>
<TSpreadsheetSourceData RowDataType="8" TransactionType="My Transaction
Type" MinorCode="2" AccountingDate="2005-02-25" OriginalCode="1234"
OriginalJobNumber="9" AdditionalInfo="None" SubCode2="4" MajorCode="1"
Description="None" Amount="56.03" InvoiceNum="54321" SubCode1="3"
TransactionDate="2005-02-18" Named="A Record"/>
<TSpreadsheetSourceData RowDataType="3" MinorCode="2" AccountingDate="2005-02-25"
OriginalCode="1248" OriginalJobNumber="17" AdditionalInfo="None" SubCode2="8"
MajorCode="1" Description="None" Amount="56.03" InvoiceNum="98765" SubCode1="4"
TransactionDate="2005-02-22" Named="Another Record">
Comma Separated Value (.csv) Files File Format A CSV file stores tabular data (numbers and text) in plain text form. Plain text means that the file is a sequence of characters where no data is interpreted as binary numbers. Note: Use Excel Find function (Ctrl + H) to check for any “stray” commas, as these need to be removed else the import will be rejected.
CSV Specification The file takes the form of a set of comma separates values where:
• Each value must be separated by a comma • Each row must be separated by a new line character (note that carriage returns are ignored throughout
the file) A new line character always marks the end of a row and the start of the next row except where it is the last character in the file in which case it is ignored. This means that the final row in the file may end with either the end of the file or be terminated with a new line character followed by the end of the file. Any white space at the start or end of any value will be ignored. All date values must be written in the format: yyyymmdd. So, for example, March 14th2015 would be written as: 20150314.
ARGUS Developer Import Actuals Data
6 © 2015 ARGUS Software, Inc.
Within a value the following character escapes may be used:
Escaped character Description
Ordinary characters Characters other than \ (backslash) and , (comma) match themselves
\t Tab
\r Carriage Return
\n New Line
\, Comma
\x20 Matches an ASCII character using hexadecimal representation (exactly two digits). For example: \x20 represents a space character
\u0020 Matches a Unicode character using hexadecimal representation (exactly four digits). For example: \x0020 represents a space character
Header Row The .csv file must contain a header row which defines what fields are to be imported into your table
Data Row Below the header row are the data rows which must contain a value for that defined field.
Imported Fields The Attribute Name and Transaction Type Table (see page 4) lists all of the standard fields that may be imported.
Example .csv File The following file:
OriginalJobNumber, MajorCode, MinorCode, SubCode1, RowDataType, InvoiceNum,
TransactionDate, Amount
J58ABC,01,01,332,3,J5813328,20140625, 145.98
J58ABC,01,01,332,3,J5813328,20140625, 145.98,
J58ABC,01,01,334,3,J5813328,20140625, 160.50
J58ABC,01,01,334,3,J5813328,20140625, 0.00
Will render the following data:
Original Job Major Code
Minor Code
Sub Code Row Data Invoice Num Transaction Amount
Number 1 Type Date
J58ABC 01 01 332 Actual/ Forecast $ J5813328 25th June 2014 145.98
J58ABC 01 01 332 Actual/Forecast $ J5813328 25th June 2014 145.98 J58ABC 01 01 334 Actual/Forecast $ J5813328 25th June 2014 160.50 J58ABC 01 01 334 Actual/Forecast $ J5813328 25th June 2014 0.00
ARGUS Developer Import Actuals Data
7 © 2015 ARGUS Software, Inc.
External Data Sources
ARGUS Developer allows source data to be imported from any external SQL Server, Oracle, ODBC or OLEDB data
source.
Before importing any data from an external data source, you first need to create an import configuration. An
import configuration defines the source of the data as well as any additional options that needs to be applied
during the import. Import configurations are created and managed in the Extension Configuration Manager
(Backstage>Import/Export>Import Data from an external source)
Opening the Configuration Manager
Go to the Backstage tab. Click the file tab and open the Backstage view
Select the Import/Export item tab.
Click on Import Actuals from External Data Source to open the Extension Configuration Manager.
Creating a new Import Configuration
Click on the Create Configuration button on the toolbar of the extension configuration manager.
Click on Project Source Data Direct Data Import. This will create a blank configuration and display the configuration wizard.
a. Select the type of connection that will be used to fetch the external data.
b. Enter the connection string for the external data source.
ARGUS Developer Import Actuals Data
8 © 2015 ARGUS Software, Inc.
c. Test the connection by pressing the Test Connection button.
d. Click Next.
e. Enter the name of the table or query to fetch the data from or select Custom Query to enter a SQL statement that selects the data from the data source.
Note: A generic SQL custom query is shown below with the following rules applied:
1. The order of the columns in the query must be precisely as shown in the Attribute Name and
Transaction Type table.
2. The length of certain fields is truncated to the same size as shown in the Maximum Length column in
the Attribute Name and Transaction Type table.
SELECT [Column_Name],103) as AccountingDate ,LEFT([Column_Name],127) as AdditionalInfo , [Column_Name] as Amount ,LEFT ([Column_Name ],127) as Description ,LEFT ([Column_Name],30) as InvoiceNum ,LEFT([Column_Name],20) as MajorCode ,LEFT ([Column_Name],20) as MinorCode ,LEFT ([Column_Name],50) as Named ,LEFT ([Column_Name ],50) as OriginalJobNumber ,LEFT ([Column_Name],20) as SubCode1 ,LEFT ([Column_Name],20) as SubCode2 , [Column_Name] as TransactionDate ,[Column_Name ] as TransactionType ,[ Column_Name] as Units ,LEFT([Column_Name],50) as OriginalCode
ARGUS Developer Import Actuals Data
9 © 2015 ARGUS Software, Inc.
,[ Column_Name] as RowDataType ,LEFT([Column_Name],32) as SourceRef ,LEFT ([Column_Name],32) as Databaseref FROM Table_Name
f. Click Next.
g. Click the Test button. This will attempt to fetch the data from the database source and will indicate any immediate problems that arise when fetching the data.
h. Click Next.
i. Click Finish to save the new configuration.
Give your new configuration a meaningful name then click Save to File. Select a local folder (not a network folder).
All fields listed in the Attribute Name and Transaction Type Table (see page 4) must be defined in the database
table.
Technical Notes
The extension configuration file must be saved locally to the workstation/PC. Configurations are not inherently
bound to a single machine and may be freely copied between machines either by direct file copying or by using the
load/save facility in the configuration manager.
Each extension configuration created is stored as a separate XML file that defines the common properties (e.g.
description, author, extension type etc.) and the extension-specific data that comprises the configuration.
ARGUS Developer Import Actuals Data
10 © 2015 ARGUS Software, Inc.
Import Actuals Data
The main method to import data is to use the the Import Actuals Data Wizard in the application
Interactive Imports
The application provides an Import Actuals Data Wizard that will guide you through the process of importing
project data. To launch the wizard, go to Import/Export in the backstage area then click Import Actuals Data.
The wizard will welcome you and then ask you to select the type of data format the actuals have been stored. You
have the option to use XML, CSV and any custom input configurations.
Select the type of data that you wish to import and click Next. The next step will be different depending on the
type of data format that you are importing.
ARGUS Developer Import Actuals Data
11 © 2015 ARGUS Software, Inc.
XML File Import
Select the XML containing actuals data. Click the [ … ] ellipsis button to browse for a file, or use the drop down
button to select a recently imported file.
Click Next to proceed and select the projects to import.
CSV File Import
Select the CSV file containing actuals data . Click the [ … ] ellipsis button to browse for a file, or use the drop down
button to select a recently imported file.
Click Next to proceed and select the projects to import.
ARGUS Developer Import Actuals Data
12 © 2015 ARGUS Software, Inc.
External Data Source Import
The wizard has all the information it needs to connect to the data source and inspect the data. You will proceed
directly to select the projects to import.
Selecting the Projects to Import
If there is a valid Job Number (i.e. project reference) held in the database, the project is displayed in the Target
Project step.
By default all the data will be imported into the listed project(s) but you can ignore the import into one or more
projects by unchecking Import against its name.
Click Next to import actuals into the database.
Adding and replacing data in the database
The software has been designed to incrementally build up a historic record of actual transactions. This means that
you only need to extract from your external data source, new data for the corresponding time period you want to
import to ARGUS Developer (it is not necessary to extract historic data again as it is already held in the database).
When the import takes place, it adds data to the database tables. If you wish to do multiple imports, this “new”
data is also added.
However, if the unique reference validation checks, matches a record with the same reference, the data associated
with that record will be replaced.
ARGUS Developer Import Actuals Data
13 © 2015 ARGUS Software, Inc.
Unattended Updates
Actuals data can be imported into the database without any user intervention using the Unattended Update function. An unattended update uses the Windows Task Scheduler or the command line to import large data sets using a server (for example) without occupying a user’s time.
Unattended Update Configurations To set up an unattended update, first create a configuration file and save it in the application folder – this is the folder where the Devwin.EXE application is held. The configuration file MUST be called ‘UpdateConfig.ini’ Create the configuration file using Notepad, or any other text editor, and add the following details:
• The name of the ARGUS Developer middleware configuration file • The user account name • The user account password • The source of the actuals data • The name of the actuals data file
To perform an unattended update, you must have Administration User rights to the application folder.
Actuals in XML Format
For actuals data in XML format, set the Extension parameter to “Source Data XML Import”. The name of the XML file is specified in the Filename parameter. For example: [Update] MiddlewareName= [use Name = xxxx found in ARGUS Developer middleware.ini] UserName= [user name you use to log on] Password= [password you use to log on] Extension=Project Source Data XML Import [Parameters] Filename=H:\My Documents\Support 20070803.xml Note: If you create an import file with a new filename, you will need to update the UpdateConfig.ini with the new filename.
Actuals in CSV Format
For actuals data in CSV format, set the Extension parameter to “Source Data CSV Import”. The name of the CSV file is specified in the Filename parameter. For example: [Update] MiddlewareName= [use Name = xxxx found in ARGUS Developer middleware.ini] UserName= [user name you use to log on] Password= [user name you use to log on] Extension=Project Source Data CSV Import [Parameters] Filename=H:\My Documents\Support 20070803.csv
ARGUS Developer Import Actuals Data
14 © 2015 ARGUS Software, Inc.
Note: If you create an import file with a new filename, you must update the UpdateConfig.ini file with the new filename.
External Data Source
For an external data source you need only specify the name of the import configuration set up in the Configuration Extension Manager.
There is no need to specify the extension because ARGUS Developer infers that the data is external data by looking at the configuration name.
[Update] MiddlewareName= [use Name = xxxx found in ARGUS Developer middleware.ini] UserName= [user name you use to log on] Password= [user name you use to log on] Configuration=Sample Database connection
Windows Task Scheduler
Once you have created and saved the UpdateConfig.ini file, set up a task to run the file.
Open Windows Task Manager (Start > Control Panel > Administrative Tools). In the Actions panel, click Create Basic
Task to open the wizard.
ARGUS Developer Import Actuals Data
15 © 2015 ARGUS Software, Inc.
Add a name and brief description then click Next.
Select the Task Trigger that specifies when you want the actuals to be imported. Click Next.
ARGUS Developer Import Actuals Data
16 © 2015 ARGUS Software, Inc.
Choose the appropriate date, time and recurrence. Click Next.
Select Start a program. Click Next.
To run the updateconfig.ini file from the command prompt when running the update through the Task Scheduler,
a .bat file must be created (in Notepad or similar), containing the following:
“@echo off
CD C:\Program Files (x86)\ARGUS Software\ARGUS Developer>"argus development budget.exe" /u
updateconfig.ini
Pause”
ARGUS Developer Import Actuals Data
17 © 2015 ARGUS Software, Inc.
Click Browse button to locate the [filename].bat in the application folder. Click Next.
A summary of the task is displayed. Click Next and the task will be listed in the Active Tasks panel.
ARGUS Developer Import Actuals Data
18 © 2015 ARGUS Software, Inc.
Logging the Result of an Unattended Update
The log from the import process is generated automatically at the end of the procedure and written to a file called:UnattendedImportLog_060703_154257.txt
Where 150703 is the date (e.g. 3rd July 2015) and 154257 is the time (e.g. 3:42pm and 57 seconds).
Log file will be saved in the following path C:\ProgramData\ARGUS Software\ARGUS Developer\Logs