RestClient API - Only the .NET version is available for now.

What is it?

An abstraction layer for accessing the Saasu REST Web Service. Contains data transfer objects (DTO) and proxy classes, which encapsulate data and method calls to remote REST WS API. Use them as if you were working with local classes.

Why?

Easier to work with classes rather than direct XML. It helps speed up integrating your application with the OLA system if you’re using .NET.

Using the API (.NET)

The API contains 5 namespaces.

Your config file settings (web.config and/or app.config)

You will need to make some additions to your config file:

1. Add the following lines to your configSections:

<configSections>
<sectionGroup name=”ola.restclient”>
<section name=”proxySettings” type=”System.Configuration.NameValueSectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089″ />
</sectionGroup>
</configSections>
</span>

2.Declare the config values for proxySettings. Add the following lines to your config file (Use the provided values for each entry. The values provided here are for illustration purpose only).

<ola.restclient>
<proxySettings>
<add key=”baseUri” value=”https://secure.saasu.com/sandbox/webservices/rest/r1/” />
<add key=”wsAccessKey” value=”TEST-REST-API” />
<add key=”fileUid” value=”99999″ />
</proxySettings>
</ola.restclient>

Simple CRUD Operations

When working with entity one at a time, you probably want to use the proxy class because it is simpler to use. The proxy class makes it easy to perform CRUD operations.

To insert/update an entity

1. Instantiate the entity dto and populate it with the required data.
2. Instantiate the entity proxy class and call the insert/update method passing the dto. Entity Uid, which identifies each entity, is not required on insert, but required on update.

Example

To insert an Account

//
// Step 1: Instantiate the entity dto and populate it with the required data.
//
TransactionCategoryDto dto = new TransactionCategoryDto();
dto.Type = AccountType.Income;
dto.Name = “Consulting Fees”;
//
// Step 2: Instantiate the proxy class and call the insert method
// passing the dto.
//
CrudProxy proxy = new TransactionCategoryProxy();
proxy.Insert(dto);

Example

To update an Account

TransactionCategoryDto dto = this.GetTransactionCategoryToUpdate();
dto.Type = AccountType.Asset;
dto.Name = “Inventory”;
//
// The dto.Uid must be > 0 when update.
//
new TransactionCategoryProxy().Update(dto);

Notes

• The WSAccessKey and FileUid are set when you instantiate the proxy class. Their values are read from the config file.
• If you need to change the WsAccessKey or FileUid on-the-fly, you can do so by setting the appropriate properties of the proxy class. E.g. proxy.FileUid = 99;
• Do not set the entity uid when you call the insert method. The uid will be set with a value generated by the system if the insert operation is completed successfully.

To retrieve an entity

Instantiate the entity proxy class, and call the get by uid method passing the entity uid.
E.g. To retrieve an Account with uid 23456 from your file

CrudProxy proxy = new TransactionCategoryProxy();
TransactionCategoryDto dto = (TransactionCategoryDto) proxy.GetByUid(23456);

To delete an entity

Instantiate the entity proxy class, and call the delete by uid method passing the entity uid.
E.g. to delete an Account with uid 23456 from your file

new TransactionCategoryProxy().Delete(23456);

Queries (Lists and Reports)

You can still use the proxy class for performing queries. To perform a query:

• Build the query by adding a search criterion to a NameValueCollection object.
• Instantiate the proxy class and call the find method passing this query object.

E.g. to find a list of unpaid sales dated between 1-Jul-05 to 31-Dec-05 for contact with uid 779, you would write:

//
// Step 1: Build query object (criteria are “AND-ed”).
//
NameValueCollection queries = new NameValueCollection();
queries.Add(”TransactionType”, TransactionType.Sale);
queries.Add(”PaidStatus”, “unpaid”);
queries.Add(”InvoiceDateFrom”, “1-Jul-05″);
queries.Add(”InvoiceDateTo”, “31-Dec-05″);
queries.Add(”ContactUid”, “779″);
queries.Add(”fields”, “InvoiceUid,InvoiceDate,DueDate,InvoiceNumber,” + “TotalAmountInclTax,AmountOwed”);
queries.Add(”sortoptions”, “DueDate ASC”);
//
// Step 2: Instantiate proxy class and call the find method.
//
InvoiceProxy proxy = new InvoiceProxy();
XmlDocument list = proxy.Find(queries);

Tasks

Proxy classes are ideal if you only deal with one entity or operation at a time. However, there are times that where you probably will need to insert multiple invoices at once into your file. Submitting the invoice one by one to the server is slow and inefficient because of overheads caused by multiple remote calls.

In this scenario, use TasksRunner to submit multiple tasks to the server at once. You can submit any tasks in a single request. They can be mixed as long as the tasks are supported by the OLA REST API.

To submit various tasks in a single request:

• Instantiate a TasksRunner class.
• Add tasks to task runner object.
• Call the execute method.

. . .
public void TestTasksRunner()
{
//
// Step 1: Instantiate TasksRunner
//
TasksRunner tasksRunner = new TasksRunner();
//
// Step 2: Add tasks.
//
tasksRunner.Tasks.Add(this.GetUpdateContactTask());
tasksRunner.Tasks.Add(this.GetInsertSaleTask1());
tasksRunner.Tasks.Add(this.GetInsertSaleTask2());
//
// Step 3: Call the execute method.
// NOTE: Check the response and results returned for errors.
//
TasksResponse response = tasksRunner.Execute();
}
public ITask GetUpdateContactTask()
{
ContactDto contactToUpdate = new ContactDto();
contactDto.Uid = 88888;
contactDto.GivenName = “Mary”;
contactDto.FamilyName = “Smith”;
IUpdateTask task = new UpdateContactTask();
task.EntityToUpdate = contactToUpdate;
return task;
}
public ITask GetInsertSaleTask1()
{
nvoiceDto dto = new InvoiceDto(TransactionType.Sale, InvoiceLayout.Service);
dto.Date = DateTime.Parse(”30-Sep-05″);
dto.ContactUid = this.MrSmith.Uid;
dto.Summary = “Test POST sale”;
dto.Status = InvoiceStatus.Invoice;
dto.InvoiceNumber = ““;
. . .
ServiceInvoiceItemDto item = new ServiceInvoiceItemDto();
item.Description = “Design & Development of REST WS”;
item.AccountUid = this.IncomeService.Uid;
item.TaxCode = TaxCode.SaleInclGst;
item.TotalAmountInclTax = 2132.51M;
dto.Items.Add(item);
. . .
return dto;
}
. . .