import actuals data - argus softwaredownloads.argussoftware.com/developer/7.10.000.170/argus...

ARGUS Developer Import Actuals Data

Import Actuals Data ARGUS Developer 7.1

December 4th, 2015

ARGUS Software – An Altus Group Company


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.

http://www.argussoftware.com/


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


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.



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"/>



<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.



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



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.

http://www.circlesoftware.com/database

http://www.w3.org/2001/XMLSchema-instance

http://www.circlesoftware.com/database.xsd



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



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.



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



,[ 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.



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.



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.



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.



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



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.



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.



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”



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.



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