oneSage SDK - Sage Schweiz...

oneSage SDK Version 2.8 Developer Start Guide

Sage Schweiz AG | Infoline 0848 686 848 [email protected] | www.sageschweiz.ch ©.Sage Schweiz AG Seite 2 von 35

1.0 Overview 3

1.1 Introduction 3

1.2 Architecture and Technology 4

1.3 Installation and deployment 4

1.4 Documentation & Developer tools 6

2.0 Supported resources (data tables) 8

2.1 Contract SageStart 8

3.0 Contract Sage50 (Sage50_Rewe) 10

4.0 Start Guide on SData Web Services 12

4.1 Developer overview 12

4.2 SData query language at a glance 13

4.3 SData compliance in oneSage 14

4.4 SData configuration 16

4.5 Sample code (C#, VB.NET, JavaScript, Java) 19

5.0 Start Guide on .NET Datasets 24

5.1 Developer overview 24

5.2 Developer tutorials (C#, VB.NET, VBA) 28

5.3 Sample code (C#) 31

6.0 Troubleshooting 35

Inhaltsverzeichnis

Überschrift 1 Arial Regular 18/21pt

mailto:[email protected]

http://www.sageschweiz.ch/


1.1 Introduction

oneSage SDK is a homogeneous interface platform for Sage Switzerland’s products.

oneSage SDK ensures a standardised flow of data between our different products and

provides a straightforward interface to connect third party products to a Sage product

at runtime.

oneSage SDK enables software partners to tightly integrate a Sage product into their

solution. The current version of oneSage SDK supports the accounting modules of Sage

50 and Sage Start.

Thanks to full .NET compatibility, oneSage SDK can be easily and seamlessly be

integrated with any .NET project by interacting with .NET Datasets.

Moreover, oneSage SDK can be accessed using its SData Web Services. SData Web

Services are implemented via RESTful web services. This means you're not limited to

using SData with a particular technology (such as exclusively via .NET)1. In a nutshell,

SData works via sending and receiving XML payloads via a URL.

This Start Guide gives a technical overview of the SDK and supports a third party

application developer with the first programming steps using oneSage SDK.

1 In this Start Guide, we provide SData sample code in C#, VB.NET, Java- and JavaScript.

1.0 Overview




1.2 Architecture and Technology

Technology: .NET Datasets and SData Web Services

oneSage SDK provides CRUD2 data operations to the databases of Sage 50 or Sage

Start. For each product, oneSage SDK provides a “contract” which represents the native

data tables of each Product3.

There are two technologies

available to access those contracts:

#1: .NET Datasets

Fully compatible .NET Datasets by

referencing the .NET assembly

oneSage.SDK.dll.

#2: SData Web Services

RESTful web requests according

open standards such as REST and

ATOM/XML. SData is a Sage Group

standard (see

http://sdata.sage.com).

1.3 Installation and deployment

oneSage SDK deployment

oneSage SDK version 2.2 is installed automatically with a Sage Start V-2012 (or later)

and with Sage 50 V-2012. If you would like to use oneSage SDK with Sage 50 V2009 or

V2011, please contact Sage Schweiz to obtain a separate installation package.

SData Web Services is a new feature in oneSage version 2.3. Version 2.3 or

higher is automatically deployed with Sage Start V-2013.0 and Sage 50 V-2013.0.

oneSage version 2.3 or higher is also compatible with Sage 50 V-2012 and is deployed

via Auto-Update.

Installation Scenario .NET Datasets

If the 3rd party product references the

oneSage SDK assembly

(oneSage.SDK.dll) for using the oneSage

.NET Datasets, both the 3rd party products

and the Sage Product (Sage 50/Start) must

be installed on the same machine.

2 CRUD = Create Read Update Delete 3 For more details about which data tables are supported, please see chapter “Supported resources / data tables”.



http://sdata.sage.com/


Installation Scenario SData Web Services

As the communication is handled by HTTP,

the 3rd party product and the Sage Product

(Sage 50/Start) must not be installed on the

same machine.

The SData Web Server is automatically installed with oneSage SDK but disabled by

default4.

.NET Datasets vs. SData

The following questions give you some guidance which technology to choose:

Question Recommendation

My application will be installed on the same machine as the Sage product & I am using .NET.

.NET Datasets

My application is not necessarily installed on the same machine as the Sage Product.

SData

I am reading or processing a large amount of data (batch processing) and processing time is highly relevant for my application.

.NET Datasets

I am reading or processing only bursts of data (no batch processing).

SData

I am using .NET technology only and I am not familiar with web technologies.

.NET Datasets

I am using other technologies than .NET. SData

System requirements

In order to install and use the oneSage SDK the following system requirements apply:

Installed Sage Product5

Sage 50: V-2009 or later (with the latest Auto-Update)

Sage Start: V-2012 or later (with the latest Auto-Update)

Windows XP/Vista/7 (32 or 64 Bit)

.NET Framework 3.5

oneSage SDK files are installed: C:\ProgramData\Sage\oneSage (Window Vista and

Windows 7) resp. C:\Documents and Settings\All Users\Application

Data\Sage\oneSage (Windows XP).

4 Chapter Enable SData Web Services explains how to enable the SData Web services. 5 Using the .NET Datasets, the 3rd party product and the Sage Product must be installed on the same machine.




1.4 Documentation & Developer tools

Documentation and developer tools for .NET Datasets

Before any coding, it is recommended to read this Start Guide and test any data

manipulation on a given database with the test program “ConnectorTestRD” first.

Document or tool File name Language

Developer Start Guide Fist programming steps for a third party application developer (this guide).

C:\Program Data\Sage\oneSage\Documentation\ oneSageSDK_StartGuide.pdf

English

Developer Reference .NET Datasets Description of oneSage SDK’s classes and properties when using the .NET Datasets (oneSage.SDK.dll). This documentation is valid for all products (Sage 50 or Start).

C:\Program Data\Sage\oneSage\Documentation\ oneSageSDK_Developer_Reference.html

English

Contract Reference Sage 50 Description of resources (table / columns) for Sage 50.

C:\Program Data\Sage\oneSage\Documentation\ oneSageSDK_Sage50_Contract.html

Deutsch

Contract Reference Sage Start Description of resources (table / columns) for Sage Start.

C:\Program Data\Sage\oneSage\Documentation\ oneSageSDK_SageStart_Contract.html

English

ConnectorTestRD.exe (C#) Simplistic tool that allows execution of all data operations on Sage 50 or Sage Start resources. For your convenience, the source code of this test program can be found in the sub folder

C:\ProgramData\Sage\oneSage\Sample\ ConnectorTestRD\ ConnectorTestRD.exe C:\ProgramData\Sage\oneSage\Sample\ ConnectorTestRD\Sourcecode

English

Excel VBA macro The Microsoft Excel document allows execution of all data operations on Sage 50 or Sage Start resources.

C:\ProgramData\Sage\oneSage\Sample\ COM Test\ oneSage.SDK.xlsm

English




Documentation and developer tools for SData Web Services

Before any coding, it is recommended to read this Start Guide and test any data

manipulation on a given database with the test program “SData Browser” first.

Document or tool File name Language

Developer Start Guide Fist programming steps developer (this guide).

C:\Program Data\Sage\oneSage\ Documentation\oneSage_StartGuide_en.pdf

English

SData Demonstration Website Website demonstrating SData for Sage 50 and Sage Start (used for sample url’s in the sample code).

http://sdata.sageschweiz.ch/ English

SData Specification The Sage Data Core Specification is –a very helpful and detailed resource about SData.

http://sdata.sage.com and http://sdata.sage.com/sdatacore.html

English

SData Tools SData Browser

Desktop application to browse and test SData queries and schemas.

Sage Integration Framework (SIF) Stand-alone installer Sage Integration Framework and the SIF Visual Studio Add-in.

SData tools and libraries Tools and libraries by the SData community are available for download on GitHub.

C:\ProgramData\Sage\oneSage\SData\Tools\ SDataBrowser.msi C:\ProgramData\Sage\oneSage\SData\Tools\ SIF Installer 1 0 0 219.exe SDataTools_for_Visual_Studio.zip http://sage.github.com/SData-2.0/

English

Excel VBA Add-in Demo Exce-Add-in what imports data from any SData URL (launched from the “Data” Ribbon within Excel)

C:\ProgramData\Sage\oneSage\SData\ Tools\SimpleSDataExcelAddin2007.xlam

English

Please note that all additional SData tools provided by the SData community and Sage

are distributed on an "as is" basis, without warranties or conditions of any kind, either

express or implied.



http://sdata.sageschweiz.ch/

http://sdata.sage.com/

http://sdata.sage.com/sdatacore.html

http://sage.github.com/SData-2.0/


2.1 Contract SageStart

All available resources and its supported data operations are listed in the table below.

Sage Start mainly supports resources from the financial accounting module.

Resource name (Plural Name)

Operations Remark

Insert Select Update Delete

Account (Accounts)

C R U D Read and edit Financial accounts (ledger)

AccountPlan (AccountPlans)

C R U D Read and edit Financial account plans (ledger)

AccountStructure (AccountStructures)

C R D Read and edit Financial account structure (ledger)

Article (Articles)

C R U D Read Articles (Sales fields only)

ArticleSet (ArticleSets)

R Read Article Sets

BankPostAccount (BankPostAccounts)

C R U D Read and edit Bank and Post accounts

Client (Clients)

C R U D Read and edit Clients

ClientDocType (ClientDocTypes)

R Read Client Document Types.

ClientDocument (ClientDocuments)

C R U D Read and edit Client Document header

ClientDocumentLine (ClientDocumentLines)

All data operations are to be executed on the parent ClientDocuments and will handle child lines

ClientPayment (ClientsPayments)

C R U D Read and edit Client payments related to a client transaction

ClientTransaction (ClientTransactions)

C1) R1) U1) D1) Read and edit Client transactions header. This resource contains all accounts receivables (“Offene Posten” /“Postes ouverts”. Accounts receivables generated from documents by the “Auftrag” module (“Gestion Commercial”) are read-only.

ClientTransactionLine1) (ClientTransactionLines)

All data operations are to be executed on the parent ClientTransaction and will handle child lines.

CostCenter (CostCenters)

C R U D Read and edit Cost centers

Currency (Currencies)

C1) R1) U1) D1) Read and edit Currencies

CurrencyRate1)

(CurrencyRates) All data operations are to be executed on parent

Currency and will handle child records.

DossierList (DossierLists)

R Read available Sage Start dossiers (all databases)

FinancialTransaction (FinancialTransactions)

C R U D Read and edit Financial transactions. This resource handles automatically all related Financial transaction lines.

FinancialTransactionLine1)

(FinancialTransactionLines) All data operations are to be executed on parent

FinancialTransaction and will handle child lines.

NumberRange (NumberRanges)

C R U D Read and edit current dossier's voucher number ranges.

Parameter (Parameters)

R U Read and edit current dossier's base parameters

PaymentCondition C R U D Read and edit Client's payment conditions

2.0 Supported resources (data tables)




(PaymentConditions)

SalaryData R U Read and edit variable Salary data

Supplier (Suppliers)

C R U D Read and edit Suppliers

SupplierBankPostAccount (SupplierBankPostAccounts)

C R U D Read and edit Supplier's bank and post accounts

SupplierDocType (SupplierDocTypes)

R Read Supplier Document Types.

SupplierDocument (SupplierDocuments)

C R U D Read and edit Supplier Document header.

SupplierDocumentLine (SupplierDocumentLines)

All data operations are to be executed on the parent SupplierDocuments and will handle child lines.

SupplierPayment (SupplierPayments)

C R U D Read and edit Supplier payments related to a supplier transaction.

SupplierTransaction1) (SupplierTransactions)

C1) R1) U1) D1) Read and edit Supplier transactions header. This resource contains all accounts receivables (“Offene Posten” /“Postes ouverts”. Accounts receivables generated from documents by the “Auftrag” module (“Gestion Commercial”) are read-only.

SupplierTransactionLine (SupplierTransactionLines)

All data operations are to be executed on parent SupplierTransaction and will handle child lines.

Unit (Units)

R Read quantity units

VAT (VATs)

C R U D Read and edit VAT categories

VATConfig (VATConfigs)

R U Read and edit VAT configuration

The available data fields (columns) per resource are documented in the

documentation „Contract Reference Sage Start“.

1) Child resources are handled over the parent resource, see CRUD on parent resources and child resources for details.




All available resources and its supported data operations are listed in the table below (in

German only at the moment). Sage 50 supports resources from the financial accounting

module.

Resource name

(Plural Name)

Operations

Remark Insert Select Update Delete

Adresse

(Adressen)

C R U D Adressen abfragen und bearbeiten.

Anschrift

(Anschriften)

C R U D Anschriften abfragen und bearbeiten.

Bank

(Banken)

C R U Anschriften abfragen und bearbeiten.

BankInfo_Debi R Bankverbindungen vom Debi-Personenkonti abfragen.

BankInfo_Kredi R Bankverbindungen vom Kredi-Personenkonti abfragen.

Bankstamm

(Bankenstamm)

C R U Bankenstamm abfragen und bearbeiten.

Beleg

(Belege)

C R U D Belege abfragen und bearbeiten.

Belegzeile

(Belegzeilen) 1)

Operationen auf Belegzeilen werden über die Elterntabelle

„Beleg“ ausgeführt.

Bucharchiv

(BuchArchive)

R Archivierten Buchungen abfragen.

Buchung

(Buchungen)

R Buchungen abfragen. Bearbeiten der Buchungen erfolgt über

die Ressource Beleg.

Dauerauftrag

(Dauerauftraege)

C R U Daueraufträge abfragen und bearbeiten.

Ini_Einstellungen R U Ini-Einstellungen abfragen und bearbeiten.

Ini_Flat

(Ini_Flat)

R U Ini-Einstellungen abfragen und bearbeiten.

Kontakt

(Kontakte)

C R U D Kontakte abgefragt und bearbeitet werden

Konto

(Konten)

C R U D Konten abfragen und bearbeiten.

Kurs

(Kurse)

C R U D Tageskurse abfragen und bearbeiten.

Mandant_DEBI R Einstellungen des Mandanten im Debi-Modus abfragen.

Mandant_FIBU R Einstellungen des Mandanten im FIBU-Modus abfragen.

Mandant_INI R Einstellungen des Mandanten im Ini-Modus abfragen.

3.0 Contract Sage50 (Sage50_Rewe)




Mandant_KREDI R Einstellungen des Mandanten im Kredi-Modus abfragen.

OP_Debi C R U D Offenen Posten der Debitoren abfragen und bearbeiten.

OP_Kredi C R U D Offenen Posten der Kreditoren abfragen und bearbeiten.

PK_Debi C R U D Personen-Konten der Debitoren abfragen und bearbeiten.

PK_Kredi C R U D Personen-Konten der Kreditoren abfragen und bearbeiten.

PLZStamm R Postleitzahlen-Stamm abfragen.

Steuer

(Steuern)

R U Steuerschlüssel abfragen und bearbeiten.

SteuerFormel

(SteuerFormeln)

R U Steuerformeln abfragen und bearbeiten.

Steuerperioden

(Steuerperioden)

R x Resource not supported. #11166

Struktur

(Strukturen)

R x x Hauptkontenplan abfragen.

Waehrung

(Waehrungen)

R U D Währungen abfragen und bearbeiten.

Zahlbed

(Zahlbedingungen)

R U Zahlungsbedingungen abfragen und bearbeiten.

The available data fields (columns) per resource are documented in the

documentation “Contract Reference Sage50_Rewe”.

1) Child resources are handled over the parent resource, see CRUD on parent resources and child resources for details.




4.1 Developer overview

What is SData?

SData is a simple, standard protocol for reading and writing data between Sage

applications. It enables desktop, server, and web-based applications to communicate with

each other, and also with third party applications and the World Wide Web.

How can SData help you?

Essential business information stored within Sage business applications is made available

throughout the organisation with ease and efficiency.

You can even use SData to make information available to remote users such as your

customers, suppliers, and your mobile sales and support teams. SData uses the World

Wide Web, so anyone with a web connection can access Sage application data via

SData.

How does it work?

To explain how SData works, let's first look at how the web works. To visit a website you

simply type in the relevant HTTP address or URL into your web browser and hit go. The

request is sent to the target website and information is then returned and displayed as a

page in your browser.

SData works in a very similar way. However in the case of SData the HTTP request is not

sent to a website but is sent to Sage software instead. Data from the software is then

returned as an RSS type feed and displayed in your browser.

You can try this for yourself if you are running Internet Explorer (version 7 or above).

Simply click on this URL: http://sdata.sageschweiz.ch:5493/sdata/sage50/sage50/-

/Konten or cut and paste it into your web browser and hit go. You are directed to a live

copy of Sage 50 hosted on the web.

You can interact with the information displayed using the search, sort and filter features in

the pane on the right.

Try typing in "Bank" in the text box on the top right. Only products with the word "Bank" in

their title or description are displayed.

Try replacing ".../Konten" on the end of the URL in your browser with ".../Adressen”

See how easy it is to get at information using SData.

4.0 Start Guide on SData Web Services



http://sdata.sageschweiz.ch:5493/sdata/sage50/sage50/-/Konten

http://sdata.sageschweiz.ch:5493/sdata/sage50/sage50/-/Konten


4.2 SData query language at a glance

This chapter gives some useful examples of how an SData query could

look like to get data from Sage 50. For a full reference of the SData query

language, please refer to the SData specification6

An SData implementation exists on our demo website http://sdata.sageschweiz.ch. These

examples show you the simplicity and the power of SData query language.

Anatomy of an SData URL

Let's start with an SData URL to get Contacts from Sage50:

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte

To understand the anatomy of the URL we can split the different segments:

http: This is the protocol. https is also allowed.

sdata.sageschweiz.ch:5493: This is the server name and port. Could be an IP

address too.

sdata: This the virtual directory. This value is imposed.

Sage50: This is the name of the application.

Sage50: This is the contract name. In this case the native contract for Sage 50.

SageDemo12: This is the dataset. That’s in fact the database name or the alias.

Kontakte: This is the resource kind (data table)

You can get more details about anatomy of an SData URL in Core Specifications7

SData registry

SData defines a registry. This registry allows SData consumers to discover the URLs of

SData providers dynamically. It facilitates the configuration of integration links between

applications:

Get the schema definition of a contract, e.g.

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/-/$schema8

Get the schema definition of a single resource, e.g. “Kontakte” resource of Sage 50

contract

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/-/Kontakte/$schema

Get the applications available, e.g.

http://sdata.sageschweiz.ch:5493/sdata/$system/registry/endpoints?where=endPointT

ype%20eq%20'application'

Get the datasets (databases) available for an application and contract, e.g. Sage 50

contract

http://sdata.sageschweiz.ch:5493/sdata/$system/registry/endpoints?where=endPointT

ype%20eq%20'dataSet' and applicationName eq 'Sage50'

6 http://interop.sage.com/daisy/sdata/Introduction.html 7 http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/ResourceCollectionURL.html 8 Hint: The schema definition URL is necessary when you use the SIF Visual Studio Add-in.




http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/-/$schema

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/-/Kontakte/$schema

http://sdata.sageschweiz.ch:5493/sdata/$system/registry/endpoints?where=endPointType%20eq%20'application'

http://sdata.sageschweiz.ch:5493/sdata/$system/registry/endpoints?where=endPointType%20eq%20'application'

http://sdata.sageschweiz.ch:5493/sdata/$system/registry/endpoints?where=endPointType%20eq%20'dataSet'%20and%20applicationName%20eq%20'Sage50'



http://interop.sage.com/daisy/sdata/Introduction.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/ResourceCollectionURL.html


You can get more details about SData registry URLs in SData Core Specification9

Queries samples

SData supports query operations on resource kinds. Queries return feeds containing

resource entries.

Filter by condition

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte?wher

e=KontaktTyp eq 2

Get entry by key

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte('1000

0.000')

Get ordering results

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte?orde

rby=Name asc

Get paging results

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte?starti

ndex=5&count=2

To build your own filter you can have a look in SData Core Specifications

4.3 SData compliance in oneSage

This section describes which SData Features are supported in oneSage according to the

SData Compliance Summary: http://interop.sage.com/daisy/sdata/662-DSY.html

Feature Supported Comments

Collection URL X

Resource URL X

Property URL

Service Operation URL

Named Query URL

Template URL X

Schema URL X

System URL X

Intermediate URL X

Query Parameters (X) Only MUST parameters supported

Query Language (X) Only basic level

Naming Conventions (X) Partial compliant. First letter of resource name is low case

Resource Versioning

Extensibility

Internationalized URLs X

9 http://interop.sage.com/daisy/sdata/423-DSY.html



http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte?where=KontaktTyp%20eq%202

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte?where=KontaktTyp%20eq%202

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte('10000.000')

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte('10000.000')

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte?orderby=Name%20asc

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte?orderby=Name%20asc

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte?startindex=5&count=2

http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/SageDemo12/Kontakte?startindex=5&count=2

http://interop.sage.com/daisy/sdata/662-DSY.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/ResourceCollectionURL.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/SingleResourceURL.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/187-DSY.html



http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/TemplateResourceURL.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/ResourceSchemaURL.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/SystemURL.html


http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/QueryParameters.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/QueryLanguage.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataURL/NamingConventionsForURLs.html






Atom feed X

Atom entry X

SData payload X

Resource linking and embedding (X) Only embedding

Error payload X

Tracking payload

Localized feeds and entries

Schema X

Schema Structure X

Service operation and named query definitions

Auxiliary type definitions

Inlined Schemas

Imported Schemas

HTTPS Encryption X

HTTP Authentication X

Sage SSO

Query/Read operation X

Query Filtering X

Query Sorting X

Query Paging X

Query/Read Payload Control X

Query/Read Caching

Query/Read on Property URL X

Query on Intermediate URL

Error Handling (all operations) X

Create operation X

Template for create X

Create on Property URL

Reliable Posting

Update operation X

Partial update

Update of child resources X

Partial return

Update on property URL

Delete operation X

Delete Concurrency control with ETag

Delete on Property URL X

X-HTTP-Method-Override

Service Operations and Named Queries

Batch Operations

Registry (X) Read only



http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataFeed/TypicalFeed.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataFeed/TypicalFeedEntry.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataFeed/ResourcePayload.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataFeed/190-DSY.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataFeed/ErrorPayload.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataFeed/TrackingPayload.html

http://interop.sage.com/daisy/sdata/AnatomyOfAnSDataFeed/188-DSY.html

http://interop.sage.com/daisy/sdata/Metadata/TypicalSDataSchema.html

http://interop.sage.com/daisy/sdata/Metadata/XSDStructure.html

http://interop.sage.com/daisy/sdata/Metadata/194-DSY.html





http://interop.sage.com/daisy/sdata/Security/Encryption.html

http://interop.sage.com/daisy/sdata/Security/Authentication.html

http://interop.sage.com/daisy/sdata/Security/424-DSY.html

http://interop.sage.com/daisy/sdata/Queries/Example.html

http://interop.sage.com/daisy/sdata/ReadOperation/Example.html

http://interop.sage.com/daisy/sdata/Queries/Filtering.html

http://interop.sage.com/daisy/sdata/Queries/Filtering.html

http://interop.sage.com/daisy/sdata/Queries/Paging.html

http://interop.sage.com/daisy/sdata/Queries/ControllingThePayload.html

http://interop.sage.com/daisy/sdata/Queries/ControllingThePayload.html

http://interop.sage.com/daisy/sdata/ReadOperation/ControllingThePayload.html

http://interop.sage.com/daisy/sdata/ReadOperation/ControllingThePayload.html

http://interop.sage.com/daisy/sdata/Queries/Caching.html

http://interop.sage.com/daisy/sdata/Queries/Caching.html

http://interop.sage.com/daisy/sdata/Queries/196-DSY.html

http://interop.sage.com/daisy/sdata/Queries/221-DSY.html

http://interop.sage.com/daisy/sdata/Queries/ErrorHandling.html

http://interop.sage.com/daisy/sdata/CreateOperation/Example.html

http://interop.sage.com/daisy/sdata/CreateOperation/UseOfTemplateURL.html

http://interop.sage.com/daisy/sdata/CreateOperation/198-DSY.html

http://interop.sage.com/daisy/sdata/CreateOperation/ReliablePosting.html

http://interop.sage.com/daisy/sdata/UpdateOperation/Example.html

http://interop.sage.com/daisy/sdata/UpdateOperation/199-DSY.html




http://interop.sage.com/daisy/sdata/DeleteOperation/Example.html

http://interop.sage.com/daisy/sdata/DeleteOperation/ConcurrencyHandling.html

http://interop.sage.com/daisy/sdata/DeleteOperation/ConcurrencyHandling.html

http://interop.sage.com/daisy/sdata/DeleteOperation/201-DSY.html

http://interop.sage.com/daisy/sdata/UpdateOperation/Example.html

http://interop.sage.com/daisy/sdata/ServiceOperations/OverviewOfServiceOperations.html

http://interop.sage.com/daisy/sdata/596-DSY/591-DSY.html

http://interop.sage.com/daisy/sdata/596-DSY/591-DSY.html




4.4 10 SData configuration

SData configuration tool

The SData Configuration tool can be launched using the shortcut “SData Configuration” in

the Windows Start Menu11. The tool allows administering the SData Web Server.

Enable SData Web Services

For security reasons, the SData Web Server is disabled by default when the Sage Product

is installed. The SData Web Server can be enabled by launching the SData Configuration

tool:

1. Launch the SData Configuration tool

2. Click [Advanced]

3. Click [Restart]

4. Check that the “SData Status” is “SData is currently running”

5. Return to the main window by clicking [Cancel]

6. Check that the Sage application is successfully registered and shown in the main

window (“Sage 50 adapter for SData” or “Sage Start adapter for SData”

Configure SData Web Server (Windows Firewall, Ports, HTTPS)

The SData Web Server can be configured

To use a different port

To use by secure HTTP protocol (https)

To be unblocked by the Windows Firewall

To access the SData Configuration settings, please launch the SData Configuration

tool and click [Advanced].

Available company datasets (=databases)

You can check the available company datasets (=databases) by launching the SData

Configuration tool:

1. Launch the SData Configuration tool

2. Click [Details] for Sage 50 or Sage Start. The tool will show the available company

datasets and its URL

10 http://interop.sage.com/daisy/sdata/Queries.html 11 Launches C:\ProgramData\Sage\oneSage\SData\Config\ Sage.SData.Service.Config.UI.exe



http://interop.sage.com/daisy/sdata/Queries.html


Please note that only databases in the applications default folder are available

only12. If you would like to access a database, which is not in the applications default

folder, you can configure a company set as an “alias” by creating a new file

C:\ProgramData\Sage\oneSage\SData\SData.config on the server.

This is sample content of such a configuration file:

<?xml version="1.0" standalone="yes"?>

<Config xmlns="http://tempuri.org/Config.xsd">

<Alias>

<Application>Sage50</Application>

<Alias>MySage50Mandant</Alias>

<Path>D:\Sage50\Rewe\MySage50Mandant</Path>

</Alias>

<Alias>

<Application>SageStart</Application>

<Alias>mySageStartDossier</Alias>

<Path>D:/SageStart/MySageStartDossier/SageStart/MySageStartDossier.SgWwr</Path>

</Alias>

</Config>

SData on Internet

By default, SData is setting the local machine name in the URLs of the responses. If your

adapters are on an Internet server you will not be able to make queries with a local

machine name in the URL. You can set your domain name in the SData Service config file

and replace your local machine name with your internet domain name, e.g.

yourdomain.ch. You have to set this value in IPAdress node in the config file:

Procedure :

1. Open C:\Program Files\Common Files\Sage SData\Sage.SData.Service.exe.config

file.

2. Edit the config file like above and add IPAddress setting where yourdomain.ch should

be change with your domain name or the public IPAddress of your server.

3. Restart the SData service.

<setting name="IPAddress" serializeAs="String"> <value>yourdomain.ch</value>

</setting>

Authentication (user name and password)

SData relies on the standard HTTP authentication protocol for authentication (RFC 2617,

Basic and digest mode).

Please refer to the SData Specification13 for more details about the authentication

protocol.

The following section describes how to protect a database of Sage 50 or Sage Start with a

user name and password.

12 This is C:\ProgramData\Sage\Data for Sage 50 and C:\Sage Data\ for Sage Start 13 http://interop.sage.com/daisy/sdata/Security/Authentication.html



http://interop.sage.com/daisy/sdata/Security/Authentication.html


Sage 50

Sage 50 allows protecting a database from accessing it by defining a password for each

“Mandant”:

1. Launch Sage 50 and open “Extras/Optionen” resp. “Extras/Options” in the menu

2. In the tab “Allgemein” resp. “General”

3. Define the password in the field “Passwort” resp. “Mot de passe”

Note: There is no user name in Sage 50. Any user name passed to SData will be ignored.

Sage Start

Sage Start allows protecting a database from accessing by defining either a password for

a “Dossier” or to enable an Advanced Mode for user management:

How to set a password (Simple Mode)

In Simple Mode, there is no user name but only one password accessing Sage Start

Dossier (like in Sage 50):

1. Launch Sage Start

2. Open “Datei/Passwort…” resp. “Dossier/Mot de passe…” in the menu and define the

password.

Note: There is no user name in Sage Start in Simple Mode. Any user name passed to

SData will be ignored.

How to set a user name and password and restrict access to data (Advanced Mode)

In Advanced mode, you can set user names and give them different access rights:

1. Launch Sage Start and open “Datei/Passwort…” resp. “Dossier/Mot de passe…” in the

menu

2. Click [Fortgeschrittener Modus] resp. [Mode avancé] and confirm that you want to

switch to the Advanced User Management Mode for this Dossier.

3. There is a user with the name “Administrator” by default. Create and modify the users

to your liking and set a password for the user(s).

4. Optionally, you can restrict the access to certain tasks and thus restrict the access of

the API.




4.5 Sample code (C#, VB.NET, JavaScript, Java)

You have different ways to make queries to SData. You can use the language of your

choice to communicate with SData at the moment the language offers HTTP request

methods. The input & output of the requests are all the time in XML.

You will find in this chapter some example to help you how to create your own query in

different languages.

.NET and the Sage Integration Framework (SIF)

If you are familiar with .NET languages, the best and recommended solution would be to

use the SIF. With the SIF you are able to work with typed objects and you don’t need to

manipulate any XML data. The library will do this and more for you.

Sample code for .NET and the SIF

A demo solution with .NET samples (C# and VB.NET) is available here:

C:\ProgramData\Sage\oneSage\ SData\ Tools\SData.Samples.zip. This console

application provides ready-to-go sample code that gets data from our demo installation on

http://sdata.sageschweiz.ch with filtering, paging and sorting. Moreover, it has samples on

how to insert/update/delete entries and how to query the SData Registry.

The demo is using the SIF Visual Studio Add-in14. This Add-in is generating typed

objects based an SData Schema URL (e.g.

http://sdata.sageschweiz.ch/sdata/Sage50/Sage50/-/$schema), This makes programming

with the SData and .NET even easier. The add-in will also automatically add the

references to the SIF dlls in your consumer project.

Deployment of the SIF

By using the SIF framework you need to have an installed the SIF Framework on the

target computer as your consumer projects needs to reference the following SIF dlls:

C:\Program Files\Sage\Assemblies\SData\Sage.Common.Syndication.dll

C:\Program Files\Sage\Assemblies\SData\Sage.Integration.Client.dll

C:\Program Files\Sage\Assemblies\SData\Sage.Integration.Server.Model.dll

C:\Program Files\Sage\Assemblies\SData\Sage.Utilities.dll

When installing Sage 50 or Sage Start, the SIF is installed automatically. Alternatively, you

can include the SIF dlls with your application or use the stand-alone installer of the SIF.15

There is more guidance for SData developers using the SIF and the Visual Studio

Add-in on the Sage UK YouTube Channel:

http://www.youtube.com/user/SageUKOfficial/videos?query=sdata

14 The add-in is here: http://sdata.sage.com/sdata11/sdatacore_showcases.html 15 The SIF stand-alone installer is here: C:\ProgramData\Sage\oneSage\SData\Tools\SIF Installer{version}.exe




http://sdata.sageschweiz.ch/sdata/Sage50/Sage50/-/$schema

http://www.youtube.com/user/SageUKOfficial/videos?query=sdata


More samples with other languages

You can find here some example with HTTP request in different language.

Read data from resource with C# (pure Web Service / XML)

Console.WriteLine("Get Data...");

string lUrl = @"http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/-/Kontakte";

HttpWebResponse lResponse = null;

HttpWebRequest lRequest = null;

lRequest = (HttpWebRequest)WebRequest.Create(lUrl);

lRequest.Method = "Get";

// get response

try {

lResponse = lRequest.GetResponse() as HttpWebResponse;

using (StreamReader sr = new StreamReader(lResponse.GetResponseStream())) {

try {

string lXml = sr.ReadToEnd();

XmlDocument lXmlDoc = new XmlDocument();

lXmlDoc.LoadXml(lXml);

Console.Write(lXml);

} catch (Exception lEx) {

Console.Write(lEx.Message);

}

}

} catch (WebException lWebEx) {

// Get error

Console.WriteLine("Exception Message :" + lWebEx.Message);

if (lWebEx.Status == WebExceptionStatus.ProtocolError) {

var lResponse2 = ((HttpWebResponse)lWebEx.Response);

Console.WriteLine("Status Code : {0}", lResponse2.StatusCode);

Console.WriteLine("Status Description : {0}", lResponse2.StatusDescription);

using (var stream = lResponse2.GetResponseStream()) {

using (var reader = new StreamReader(stream)) {

var text = reader.ReadToEnd();

Console.WriteLine(text);

}

}

}

} finally {

// Close connection

lResponse.Close();

}

In addition, there is a generic C# library provided by the SData Community on GitHub :https://github.com/Sage/SDataCSharpClientLib This library provides helper classes for the consumption of SData services with C#.



https://github.com/Sage/SDataCSharpClientLib


Read data from resource with VB .NET (pure Web Service / XML)

Console.WriteLine("Get Data...")

Dim lUrl As String = "http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/-/Kontakte"

Dim lResponse As HttpWebResponse = Nothing

Dim lRequest As HttpWebRequest = Nothing

lRequest = DirectCast(WebRequest.Create(lUrl), HttpWebRequest)

lRequest.Method = "Get"

' get response

Try

lResponse = TryCast(lRequest.GetResponse(), HttpWebResponse)

Using sr As New StreamReader(lResponse.GetResponseStream())

Try

Dim lXml As String = sr.ReadToEnd()

Dim lXmlDoc As New XmlDocument()

lXmlDoc.LoadXml(lXml)

Console.Write(lXml)

Catch lEx As Exception

Console.Write(lEx.Message)

End Try

End Using

Catch lWebEx As WebException

' Get error

Console.WriteLine("Exception Message :" + lWebEx.Message)

If lWebEx.Status = WebExceptionStatus.ProtocolError Then

Dim lResponse2 = DirectCast(lWebEx.Response, HttpWebResponse)

Console.WriteLine("Status Code : {0}", lResponse2.StatusCode)

Console.WriteLine("Status Description : {0}", lResponse2.StatusDescription)

Using stream = lResponse2.GetResponseStream()

Using reader = New StreamReader(stream)

Dim text = reader.ReadToEnd()

Console.WriteLine(text)

End Using

End Using

End If

Finally

' Close connection

lResponse.Close()

End Try




Read data from resource with JavaScript

// start this sample by using wscript from the command line:

WScript.Echo("Get contacts...");

// create an http object to retrieve the sdata feed

// ms Xml version 3.0 should be installed on most windows installations

// you can also choose an other xml version

var http = WScript.CreateObject("Msxml2.XMLHTTP.3.0");

// Initializes an MSXML2.XMLHTTP request and specifies the method, URL

// and authentication information for the request.

http.open("GET", "http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/-/Kontakte", false,

"", "");

// send the HTTP request

http.send();

// create a xml document

var doc = WScript.CreateObject("Msxml2.DOMDocument.3.0");

// load the http response stream into the xml document

doc.loadXML(http.responseText);

// set all namespaces needed to select the sdata elements

var ns = "xmlns:Sage50=http://schemas.sage.com/ch/Sage50' ";

ns = ns + "xmlns:sdata='http://schemas.sage.com/sdata/2008/1' ";

doc.setProperty("SelectionNamespaces", ns);

// select all atom entries inside the xml document

var entries = doc.documentElement.selectNodes("//entry");

//WScript.Echo(entries.item(0).selectSingleNode("sdata:payload/Kontakte").xml);

WScript.Echo(doc.documentElement.xml);

// output the number of requested entries

WScript.Echo("The requested feed contains " + entries.length + " entries.");

var output = '';

// iterate thru all requested entries

for (var i = 0; i < entries.length; i++) {

// select the contact node

var entry = entries.item(i).selectSingleNode("sdata:payload/Kontakt");

// select the ID of the contact

output += entry.selectSingleNode("KontaktNr").text + " | ";

//output += "---------------------------------------------\n";

}

// output the contact

WScript.Echo(output);

In addition, there is a generic JavaScript library provided by the SData Community

on GitHub: https://github.com/Sage/SDataJavaScriptClientLib

This library provides helper classes for the consumption of SData services with

JavaScript.



https://github.com/Sage/SDataJavaScriptClientLib


Read data from resource with JAVA

System.out.println("Get data...");

String URI = "http://sdata.sageschweiz.ch:5493/sdata/Sage50/Sage50/-/Kontakte";

try {

// Open connection

URL url = new URL(URI);

HttpURLConnection httpCon = (HttpURLConnection) url.openConnection();

httpCon.setDoOutput(true);

httpCon.setRequestMethod("GET");

// Get Response

InputStream is = httpCon.getInputStream();

// Display result

BufferedReader rd = new BufferedReader(new InputStreamReader(is));

String line;

StringBuffer response = new StringBuffer();

while((line = rd.readLine()) != null) {

response.append(line);

response.append('\r');

}

rd.close();

System.out.println(response.toString());

} catch(Exception e) {

throw new RuntimeException(e);

}




5.1 Developer overview

Data operation pattern with oneSage

There are four basic programming steps in order to execute a data operation:

1. Create Connection object

2. Create Adapter object

3. Modify data in the .NET dataset

4. Run Adapter.Execute method to execute data operations in the application’s

database

In Step 3 and 4 the data will be modified in .NET and sent to the application as follows:

1. A row in the .NET data table will be added, modified or deleted (the RowState will be

set accordingly)

2. The row will be sent to oneSage (using the Adapter.Execute method)

3. oneSage adds/modifies/deletes the record in the database of the target application’s

database according the RowState and the chosen data operation.

4. oneSage returns the updated data and refreshes your .NET data set

1. Create Connection object

The Connection class contains all information for a connection to a Sage Product. The

following parameters must be provided to initialise an object:

Contract

The used contract for the application, e.g. „Sage50_Rewe“ or „SageStart“. Internally,

this is an XSD-File (XML-Schema) that contains all the resource definitions (which

data tables are supported for this product).

Connector: ConnectionString

The ConnectionString is used by the Connector of the product to access the

application resp. its database. Typically this contains the path to the database and a

user name and password.16

Please see SData chapter Authentication (user name and password) on how setting

up database passwords in Sage Start and Sage 50.

Application: Sage Start or Sage 50

Defines which product will be connected: „Sage50“ or „SageStart“.

16 You can use the test program to generate a ConnectionString.

5.0 Start Guide on .NET Datasets




2. Create Adapter object

The Adapter class provides the data operations. In order to initialise the adapter object,

only a valid connection object is needed.

3. Execute data operations

By passing the .NET data table to the Adapter.Execute method, the following data

operations can be performed:

1. Select Get records from the application’s database

2. Update Modify records in the application’s database (according .NET data set)

3. Insert Add records in the application’s database (according .NET data set)

4. Delete Delete records in the application’s database (according .NET data set)

There is a detailed description of the Adapter.Execute Method in the „oneSage

Developer Reference“.

Please note that Sage 50 and Sage Start provide product specific data tables. Using the

SDK, those tables are accessed with a „resource”, e.g. „Account“. The supported

resources can be found in the chapter “Supported resources / data tables” and in the

documentation „Contract Reference“ for each product.

Sample Code: Creating a new ledger account in Sage Start

// Step #1: Create Connection object

oneSage.SDK.RD.Access.Connection lConnection =

new oneSage.SDK.RD.Access.Connection("SageStart",

@"@user=;@password=;" +

"@path=!Srv!Standard:myServerName/" +

"C:/Sage Data/Folders/Meine Firma/Sage

Start/Meine Firma.SgWwr",

"SageStart");

// Create InfoList object to get back error messages

oneSage.SDK.RD.Validating.InfoList lInfoList = new oneSage.SDK.RD.Validating.InfoList();

if (lConnection.DoValidate((oneSage.SDK.RD.Validating.Interface.IInfoList)lInfoList) ==

true) {

// Step #2: Create Adapter object oneSage.SDK.RD.Access.Adapter lAdapter = new

oneSage.SDK.RD.Access.Adapter(lConnection);

// Step #3: Create data set, tables, rows for data operations

oneSage.SDK.RD.Data.SageStart lDataSet = new oneSage.SDK.RD.Data.SageStart();

oneSage.SDK.RD.Data.SageStart.AccountDataTable lTbl = lDataSet.Account;

oneSage.SDK.RD.Data.SageStart.AccountRow lRow = lTbl.NewAccountRow();

lRow.AccCode = "9999"4;

lRow.DescDe = lRow.DescFr = lRow.DescEn = lRow.DescIt = "My new account";

lTbl.AddAccountRow(lRow);

// Step #4: Execute SDK operation for table Account: Insert new rows into database

lAdapter.Execute(oneSage.SDK.RD.Access.Operation.Insert, lDataSet, lTbl.TableName,

lInfoList);

}

More sample code is available in the chapter “Sample programs and code”.




Tables and columns attributes

.NET DataTables within a .NET DataSet is the technical base for all data operations with

oneSage SDK. For the developer’s convenience, all .NET DataTables are strongly

typed. Consequently, all resources with their properties and fields can be accessed using

their field names and are verified during compilation.

Moreover, all important information about a field can be accessed through the standard

.NET properties of the table and columns, such as

Is a field a Primary Key

Is a field read only (ReadOnly)

Is a field mandatory when creating a new record (AllowDBNull)

What is the maximum length of a string field (MaxLength)

What is the end user name of the field (Caption, CaptionDE, CaptionFR)

CRUD on parent resources and child resources

Records in child resources are generally handled by executing the

Insert/Select/Update/Delete operation on the parent resource:

Insert: When inserting a parent resource, the added child resource will be inserted

automatically as well.

Select: Reads the parent resource and all related child lines into the dataset.

Update: An “Update” on the header does process any deleted, modified or added child

resources automatically.

Delete: Deleting the parent resource automatically deletes all related child resources.




Error and Exception Handling

The SDK does not generate exceptions for any business logic errors. All error messages

or warnings are handled with an InfoList object. The InfoList object contains a list of items

which can easily be accessed:

Please note, that.NET will throw exceptions if you want to insert invalid data into the.NET

data tables, such as duplicate Primary Keys, Null values in mandatory fields, modifying

read only fields etc.

Sample code enhanced with error and exception handling:

// Step #1: Create Connection object



@"@user=;@password=;" +

"@path=!Srv!Standard:myServerName/" +

"C:/Sage Data/Folders/Meine Firma/SageStart/Meine

Firma.SgWwr",

"SageStart");


if (lConnection.DoValidate((oneSage.SDK.RD.Validating.Interface.IInfoList)lInfoList) ==

true) {

try {

// Step #2: Create Adapter object

oneSage.SDK.RD.Access.Adapter lAdapter = new

oneSage.SDK.RD.Access.Adapter(lConnection);

// Step #3: Create data set, tables, rows for data operations

// Create new and empty Sage Start data set


oneSage.SDK.RD.Data.SageStart.AccountDataTable lTbl = lDataSet.Account;

oneSage.SDK.RD.Data.SageStart.AccountRow lRow = lTbl.NewAccountRow();

lRow.AccCode = "9999";

lRow.DescDe = lRow.DescFr = lRow.DescEn = lRow.DescIt = "My new account";

lTbl.AddAccountRow(lRow);

// Step #4: Execute SDK operation (Insert) and write all rows the database

lAdapter.Execute(oneSage.SDK.RD.Access.Operation.Insert, lDataSet, lTblName,

lInfoList);

} catch (SystemException lExp) {

// Catch any exception thrown by the .NET data set (e.g. Primary Key, AllowDBNull,

ReadOnly)

// Show error by re-using SDK's InfoList

lInfoList.Add(new

oneSage.SDK.RD.Validating.Info(oneSage.SDK.RD.Validating.InfoTypes.Error,

DateTime.Now,

lExp.Message,

"MyApplication",

"Manipulating data set"));

}

// Show error messages if any

System.Text.StringBuilder lMessageBuilder = new StringBuilder();

foreach (oneSage.SDK.RD.Validating.Info lInfo in lInfoList) {

if ((int)lInfo.InfoType < (int)oneSage.SDK.RD.Validating.InfoTypes.CriticalError) {

lMessageBuilder.Append(lInfo.InfoType + " (" + lInfo.DateTime + "): " +

lInfo.Method + "/"

lInfo.Message + "\r\n");

}

}

if (!string.IsNullOrEmpty(lMessageBuilder.ToString()))

MessageBox.Show(lMessageBuilder.ToString(), "Info List", MessageBoxButtons.OK,

MessageBoxIcon.Information);

}




5.2 Developer tutorials (C#, VB.NET, VBA)

In this section you will find a step-by-step tutorial on how to create a new SDK project and

use the .NET assembly to use oneSage SDK with the NET datasets.

There are two tutorials:

1. .NET C# and VB.NET

Integration into a.NET project with Microsoft Visual Studio and VB. NET or C#

2. MS Office VBA Macro

Integration into MS Office (e.g. Microsoft Excel) with VBA and COM

The code syntax is the same for all products, as the SDK provides a common interface to

all the Sage products. But there are two major differences depending on the target

product:

Parameter settings are different in the Connection object.

The data sets and data tables (resources) are product specific

Here you see how the parameters are different between two products:

%Applicatio

n%

%ConnectionString% %Contract

%

%Resourc

e%

Sage50 @path=C:\ProgramData\Sage\Data\Rewe\SageDemo12;@

password=

Sage50_Rewe Konto

SageStart @user=;@password=;

@path=!Srv!Standard:myServerName/C:/Sage

Data/Folders/

SageDemo/SageStart/SageDemo.SgWwr 17

SageStart Account

In the following code samples, you can replace the key words (e.g. %Application%) with

the values illustrated in the table above (e.g. „Sage50“ or „SageStart“).

“Network Mode” in Sage Start

Please note that an access to a Sage Start database must be accessed in “Network

mode” by using the following syntax !Srv!Standard:[IP-Adress or Servername]/[Local

Path to database file], e.g. !Srv!Standard:myServerName/C:/Sage Data/Folders/

SageDemo/SageStart/SageDemo.SgWwr.

Also in the Sage Start application the database must be accessed in “Network mode”.18

If any application accesses the database in “Local mode”, the database will be locked

exclusively for this application and no other application or user can access this database.

17 The parameters “@folder” and “@dossier” are obsolete not necessary anymore from SDK Version 2.1 and later. The parameter “@path” covers the full path to the Sage Start database. 18 The Sage Start database is in Network mode if the Sage Start window caption contains the [Netzwerk] resp [Réseau] and does not contain [lokal] resp. [locale].




Tutorial .NET project (C# and VB.NET)

This chapter describes how you create a new .NET project and read and display data

from oneSage SDK.

Add a reference to a new .NET project

1. Create a new „Windows Forms Application“ project

2. By adding a reference you can access oneSage SDK in your project: Select your

project in the Solution Explorer and run the context menu command Add Reference.19

3. In the tab „.NET“, select the assembly oneSage.SDK and confirm with OK. The

assembly reflects the %InstallDir%\oneSage.SDK.dll.

4. oneSage classes and methods are now available in your project (see object)

Form design

1. Add a DataGridView control on your from

2. Add a Button control on your form

Add your code

1. Double click on your button

2. Add the sample code below to the button1_Click method

3. Run your application with F5.

Sample code C# //Set the connection object


new oneSage.SDK.RD.Access.Connection("%Application%",

@"%ConnectionString%",

"%Contract%");

oneSage.SDK.RD.Access.Adapter lAdapter = new oneSage.SDK.RD.Access.Adapter(lConnection);


//Execute Query

lAdapter.Execute(oneSage.SDK.RD.Access.Operation.Select,

lDataSet,

"%Ressource%",

lInfoList);

//DataBinding

dataGridView1.DataSource = lDataSet.Tables["%Ressource%"];

Sample code VB.NET 'Set the connection object

Dim lConnection As New oneSage.SDK.RD.Access.Connection("%Application%",

"%ConnectionString%",

"%Contract%")

Dim lAdapter As New oneSage.SDK.RD.Access.Adapter(lConnection)

Dim lInfoList As New oneSage.SDK.RD.Validating.InfoList()

'Execute Query

Dim lDataSet As DataSet = CType(lAdapter.Execute(oneSage.SDK.RD.Access.Operation.Select,

"%Ressource%",

new string() {},

lInfoList), DataSet)

'DataBinding

dataGridView1.DataSource = lDataSet.Tables("%Ressource%")

19 This command can also be run from the main menu (Project/Add Reference)




Tutorial Microsoft Office VBA Macro

This chapter describes how you can read and display data from oneSage SDK using

Microsoft Excel 2010.

Set-up an Excel spread sheet

1. Create a new Microsoft Excel spread sheet.

2. Switch to developer mode with Alt+F11

3. By adding a reference you can access oneSage SDK in your project: In the VBA-

Editor, go to run the Tools/References and select and confirm the assembly

oneSage.SDK in the references dialog. The assembly reflects the

%InstallDir%\oneSage.SDK.dll.

Form design

1. Switch back to the Excel spread sheet.

2. Activate the design mode and add a Button on your spread sheet.

Add VBA code

1. Switch to the developer environment (Alt+F11) and go to the code of Button1_Click.

2. Insert the sample code below

3. Replace the place holder with meaningful values (e.g. „%Application%“ with

„SageStart“)

4. Close the developer environment and deactivate the design mode

5. Click on the button to show the data in Excel.

Sample code VBA On Error Resume Next

'Define variables

Dim lConnection As New Connection

Dim lAdapter As New Adapter

Dim lInfoList As New InfoList

Dim lDataSet As DataSet

Dim lRessource As String

lRessource = "%Ressource%"

'Set the connection object

lConnection.Application = "%Application%"

lConnection.Contract = "%Contract%"

lConnection.ConnectionString = "%ConnectionString%"

Set lAdapter.Connection = lConnection

'Execute Query

Set lDataSet = lAdapter.Execute(Operation_Select, Nothing, lRessource, "", "", Nothing, "",

lInfoList)

'Show Data in Excel Sheet

'Clear Worksheet

Range("A4:CF704").Select

Selection.ClearContents

Range("A1:A1").Select

'Fill the result into the Excelsheet

Dim lDataRow As IDataRow

Dim lRowCount As Integer

Dim lValue As String

Dim lColumnCount As Long

'Create Header

For lColumnCount = 0 To lDataSet.Tables.Item_2(lRessource).Columns.Count - 1

ActiveSheet.Cells(5, lColumnCount + 1) =

lDataSet.Tables.Item_2(lRessource).Columns(lColumnCount).ColumnName

Next




'Fill Data

For lRowCount = 0 To lDataSet.Tables.Item_2(lRessource).Rows.Count - 1

Set lDataRow = lDataSet.Tables.Item_2(lRessource).Rows(lRowCount)

For lColumnCount = 0 To lDataSet.Tables.Item_2(lRessource).Columns.Count - 1

lValue = lDataRow.Item_2(lColumnCount)

ActiveSheet.Cells(lRowCount + 6, lColumnCount + 1) = lValue

Next

Next

5.3 Sample code (C#)

The following sections demonstrate the use of oneSage SDK and .NET datasets using C#

and Sage Start.

Modify data // Set-up connection to application and database




"SageStart");



// Query data

oneSage.SDK.RD.Data.SageStart lDataSet =

(oneSage.SDK.RD.Data.SageStart)lAdapter.Execute(oneSage.SDK.RD.Access.Operation.Select,

"VAT",

new string[] { },

lInfoList);

//Modify data

oneSage.SDK.RD.Data.SageStart.VATDataTable lTblAccount = lDataSet.VAT;

oneSage.SDK.RD.Data.SageStart.VATRow lRow =

(oneSage.SDK.RD.Data.SageStart.VATRow)lTblAccount.Rows[0];

lRow.DescDe = "Modified - Einlageentsteuerung 8.0%";

// Send data

lAdapter.Execute(oneSage.SDK.RD.Access.Operation.Update,

(oneSage.SDK.RD.Data.Interface.IDataSet)lDataSet,

"VAT", "", "", null, "", lInfoList);

Insert data // Set-up connection to application and database




"SageStart");



// Create new data set


// Create new row in data table

oneSage.SDK.RD.Data.SageStart.VATDataTable lTblVat = lDataSet.VAT;

oneSage.SDK.RD.Data.SageStart.VATRow lRow = lTblVat.NewVATRow();

lRow.VatCode = "EIN80";

lRow.DescDe = "Einlageentsteuerung 8.0%";

lRow.Rate = 8;

lRow.Ratio = 100;

lRow.AccCode = "1170";

lRow.VatType = 3;

lRow.SaldoRate = 0;

TblVat.AddVATRow(lRow);

// Send added data rows to database

lAdapter.Execute(oneSage.SDK.RD.Access.Operation.Insert,


"VAT", "", "", null, "", lInfoList);




Delete data // Set-up connection to application and database




"SageStart");



// Query data



"VAT",

new string[] { },

lInfoList);

// Delete first row

oneSage.SDK.RD.Data.SageStart.VATDataTable lTblVat = lDataSet.VAT;

oneSage.SDK.RD.Data.SageStart.VATRow lRow =

(oneSage.SDK.RD.Data.SageStart.VATRow)lTblVat.Rows[0];

lRow.Delete();

// Send data

lAdapter.Execute(oneSage.SDK.RD.Access.Operation.Delete,


"VAT",

"",

"",

null,

"",

lInfoList);

Query data (with filter and sort) // Set-up connection to application and database




"SageStart");



// Query data

string lFilter = "VatCode>'1170'"; // Filter- and sort expressions correspond

with

string lSort = "VatCode,AccCode"; // the .NET DataColumn.Expression property.

string lFillFields = "VatCode,AccCode,DescDe";



"VAT",

lFilter,

lSort,

lFillFields.Split(','),

lInfoList);




Query data (with paging) // Set-up connection to application and database




"SageStart");



// Query data

string lFilter = "VatCode>'1170'";

string lSort = "VatCode,AccCode";

string lFillFields = "VatCode,AccCode,DescDe";

// Paging data

oneSage.SDK.RD.Access.Paging lPaging = new oneSage.SDK.RD.Access.Paging();

lPaging.Count = 10; // Step

lPaging.Start = 0; // Start, zero based

do {

oneSage.SDK.RD.Data.SageStart lSageStart = null;

lSageStart =

(oneSage.SDK.RD.Data.SageStart)mAdapter.Execute(oneSage.SDK.RD.Access.Operation.Select,

"VAT",

lFilter,

lSort,

lPaging,

lFillFields,

lInfoList);

foreach (oneSage.SDK.RD.Data.SageStart.VATRow lVATRow in lSageStart.VAT.Rows) {

Console.WriteLine(lVATRow.VatCode);

++lPaging.Start;

}

Console.WriteLine("Continue? (Y/N):");

if (Console.ReadKey(true).Key != ConsoleKey.Y) {

break;

}

} while (lPaging.Start < lPaging.TotalRecords);




Insert data (with relating tables) // Insert a financial transaction. This must include a minimum of two lines.

// All financial transaction operations must execute over the header. E.g a delete/

// insert or update from a line.

// A transaction with her lines must be balanced in itself.

// Set-up connection to application and database




"SageStart");



// Create new data set


// Add new row in FinancialTransaction

oneSage.SDK.RD.Data.SageStart.FinancialTransactionDataTable lTblFinTrans =

lDataSet.FinancialTransaction; oneSage.SDK.RD.Data.SageStart.FinancialTransactionRow lHeaderRow =

lTblFinTrans.NewFinancialTransactionRow(); lHeaderRow.ValutaDate = DateTime.Today;

lHeaderRow.HeaderText = "oneSage Testbuchung 01";

lTblFinTrans.AddFinancialTransactionRow(lHeaderRow);

// Add new rows in FinancialTransactionLine

oneSage.SDK.RD.Data.SageStart.FinancialTransactionLineDataTable lTblFinTransLine =

lDataSet.FinancialTransactionLine;

// Debit row

oneSage.SDK.RD.Data.SageStart.FinancialTransactionLineRow lLineRowDebit =

lTblFinTransLine.NewFinancialTransactionLineRow(); lLineRowDebit.HeaderId = lHeaderRow.HeaderId; // Set relation to Header

lLineRowDebit.AccountCode = "1000";

lLineRowDebit.AmountExclVatMc = 1200;

lLineRowDebit.DebiCredi = 1;

lTblFinTransLine.AddFinancialTransactionLineRow(lLineRowDebit);

// Add first credit row

oneSage.SDK.RD.Data.SageStart.FinancialTransactionLineRow lLineRowCredit1 =

lTblFinTransLine.NewFinancialTransactionLineRow();

lLineRowCredit1.HeaderId = lHeaderRow.HeaderId; // Set relation to Header

lLineRowCredit1.AccountCode = "1020";

lLineRowCredit1.AmountExclVatMc = 1000;

lLineRowCredit1.DebiCredi = 2;

lTblFinTransLine.AddFinancialTransactionLineRow(lLineRowCredit1);

// Add second credit row

oneSage.SDK.RD.Data.SageStart.FinancialTransactionLineRow lLineRowCredit2 =

lTblFinTransLine.NewFinancialTransactionLineRow(); lLineRowCredit2.HeaderId = lHeaderRow.HeaderId; // Set relation to Header

lLineRowCredit2.AccountCode = "1021";

lLineRowCredit2.AmountExclVatMc = 200;

lLineRowCredit2.DebiCredi = 2;

lTblFinTransLine.AddFinancialTransactionLineRow(lLineRowCredit2);

// Send added data rows to database

lAdapter.Execute(oneSage.SDK.RD.Access.Operation.Insert,


lTblFinTrans.TableName,

lInfoList);




This section will list known problems and its solutions.

Sage Start

SData request to Sage Start results in error Error 8000401a

An SData request reports the following error message: „COMExcpetion: Die COM-

Klassenfactory für die Komponente mit CLSID {1001B580-4000-0003-AEB4-

0000E80C11B9} konnte aufgrund des folgenden Fehlers nicht abgerufen werden:

8000401a.“

Solution: In order that Sage Start application and SData can run simultaneously, SData

for Sage Start is configured to use the “Interactive User” and thus needs a logged-in

windows user. Please ensure that there is a logged-in windows user where Sage Start is

running.

6.0 Troubleshooting



oneSage SDK - Sage Schweiz...

Documents

Transcript of oneSage SDK - Sage Schweiz...