AyaNova business object library quick start guide

This is a quick start guide for experienced developers.

If you have any questions after reading this guide and examining the sample applications we will be happy to answer them on the AyaNova development forum at http://forum.ayanova.com 

About 

AyaNova is built upon the AyaNova business object library.  This is a code library that handles all of the details of working with AyaNova objects such as Clients, Workorders etc.

All the AyaNova programs and utilities use this shared library and you can too.  The library is free for commercial or private use.  In other words you can write a utility for your own shop or a program that you sell commercialy as an add-on for AyaNova.  We provide free support through the forum and the api documentation.

The windows AyaNova program and the asp.net WBI web interface were both built using this exact same business object library so as you can see it's quite powerful but also easy to use.

The AyaNova business object library is written in and supports the .net framework 3.5 or newer.  If you are not familiar with the .net framework there is a good article in Wikipedia about it: http://en.wikipedia.org/wiki/.NET_Framework

What kind of program can I write?

You have two choices for developing an application for AyaNova: as a stand alone application (windows or web) or as a plugin for use from within the AyaNova program itself.

Requirements

To develop an application that can work with the AyaNova business object library you need the following:

Your development computer must have a working copy of AyaNova on it.  Ideally just install the latest trial version which is perfect for test and development because you won’t be using a live database.  You do *not* need a license to develop for AyaNova, in fact you do not need to buy anything at all.

This should go without saying, but we will say it anyway, do not develop an application against your live in-use AyaNova database.  Testing will often require blowing away the database and mistakes are bound to happen.

A .net development tool. We use Visual Studio Professional from Microsoft, however, you can use anything that supports .net
Here are some free ones:
Microsoft Visual Studio Express - http://www.microsoft.com/express/
Sharp Develop - http://www.sharpdevelop.net/OpenSource/SD/Default.aspx

Internet access to the online AyaNova API documentation at: http://api.ayanova.com

Distributing your program

Once your application is ready for release you can simply drop the executable and manifest into the AyaNova program folder if it's a stand alone application or the plugin .dll file under the plugins folder for plugins, you do not need to distribute any of the files that come with AyaNova that you used for development since these are the same files that come with AyaNova itself anyway.  

Royalties, license fees, what does it cost me to develop for AyaNova

Nothing. Our business is with AyaNova and we think a free an open environment for 3rd party developers can only be a good thing for our customers.  

Integrating other applications with AyaNova

AyaNova business object library has built in integration objects that are provided just for the purpose of 3rd party developers integrating other applications with AyaNova.  It's the same objects that our own add-on products such as QBI and PTI use to store the data that helps them integrate between AyaNova and QuickBooks and Peachtree.  We encourage developers to have a look at these objects and take advantage of them if they will be beneficial.
See the developers API documentation at http://api.ayanova.com  and have a look at the objects that start with the word "Integration" for more details.

Programming languages supported

The AyaNova business object library was coded to conform to .net Common Language Infrastructure standards and as such you should have no problem 
using the .net framework language of your choice.  We code primarily in C#, but that has no relevance on what language
you may choose to use, the AyaNova business objects are language agnostic, you can use any of the following:
C++ (managed, i.e. .net)
C#
Visual Basic .Net
J# - Java for .net
Or anything else that supports .net

A complete list can be found here:
http://en.wikipedia.org/wiki/CLI_Languages

Our examples will be primarily in C# with a limited number in Visual Basic.net however the concepts are the same and the code will be
almost identical when it relates to the AyaNova business objects.

In general

AyaNova installs with the developers API so there is nothing else to download or install, however you will need to copy some files from the AyaNova program files folder to your development folder in order to keep your work separate while developing.  Once you have those files copied you just need to add a reference in your project and you're ready to go.

Note that when your program is ready for release you no longer need to worry about distributing or copying any of the referenced or FireBird files on the end users computer because you can simply drop your single executable in the AyaNova program file folder or plugin .dll in the AyaNova program file folder's Plugins subdirectory and all the required files will be there already.

Getting started step by step

The best way to learn how to develop for AyaNova is to examine the sample projects, we provide samples for both stand alone applications and Plugins which are copiously documented.

•	Download and install AyaNova, take all the defaults or make note of where you install to if you are installing a second copy only for development.  Run AyaNova and confirm it works.
•	Create your initial empty project in the language and development environment of your choice
•	Add references to the business object library by browsing to the AyaNova installation folder and selecting the 6 .dll files that make up the business object library and it's supporting components: GZTW.AyaNova.BLL.dll, GZTW.Data.dll, GZTW.Profile.dll, CSLA.dll, CSLA.Server.DataPortal.dll, CSLA.Core.Bindablebase.dll 
•	Add a reference to the .net Firebird database driver in the AyaNova installation folder: FirebirdSql.Data.FirebirdClient.dll
•	Copy the FireBird database driver files from the AyaNova program files folder to the output folder where your program will be run from during development.  (normally the /bin/Debug folder)  The files are: fbembed.dll, firebird.msg, cudt30.dll, icuin30.dll and icuuc30.dll
•	Copy the config.txt file from the AyaNova program files folder to your projects bin/debug folder so that your application will use the same database as the AyaNova you installed in the first step.
•	Add a "Using" statement at the top of your code file to reference GZTW.AyaNova.BLL to save typing, see the samples for more details.
•	If you are writing a stand alone application then every operation with the AyaNova business object library will require that the user login first.  The examples show how to do this.  You can do it automatically in code with a set login name and password or prompt for it, however you like, but you cannot use the business object library until you are authenticated.
•	If you are writing a plugin you do not need to concern yourself with authentication.

Windows Vista / Windows 7

The AyaNova business object library is fully compatible with Windows Vista and Windows 7.

If there is any possibility that your application you are developing will be run on Windows Vista or Windows 7 it's very important that you include or embed a manifest file with your application to ensure that UAC Virtualization does *not* take place.

You can avoid a world of confusion debugging issues on Vista / 7 by using a manifest with your application and it has no effect on other older operating systems so the bottom line is just do it. :)

The HelloAyaNova sample includes a manifest file with the correct settings for the Ayanova business object library which does not require elevated privileges under Vista.  If your application does you will of course need to change this, however for now simply make sure you include the manifest with your executable and change the name and version tags to match your application.

About the AyaNova business objects

The AyaNova business object library is composed of 6 basic types of objects they can be recognized by their static/shared methods.  The basic types are:
•	Read only objects - a single object that generally is used internally by AyaNova to retrieve a count or a name or check the existance of an object
•	Read only collection objects - a collection of objects generally used for list used for display or selection like a ClientPickList
•	Editable Root objects - a single object that can be modified and saved.  Typically these represent a real world object in AyaNova like a Client or a Workorder.  
•	Editable Child objects - a single object that is not directly created or deleted on it's own but exists within a collection linked to another object.  For example a ClientNote is an editable child object that exists within a collection of ClientNotes which is contained within a Client editable root object.
•	Editable Child Collection objects - a collection of Editable Child objects which is contained within another object.  All create, delete and updates of child objects are done through this collection object.
•	Editable Root Collection objects - a collection of editable child objects which stands on it's own without being contained inside another object.  Typically this is objects that are almost always worked with as collections in the user interface of AyaNova rather than one by one.  For example DispatchZones are an editable root collection because they are worked with in the AyaNova user interface in a list, there is no need to open a single dispatch zone to edit it because it only contains a name and an ID value so doesn't require a full screen for editing such as for more complex objects like a Client

No direct instantiation

Without exception every AyaNova business object is retrieved or created using a shared / static method of that object, never by direct instantiation.  
For example, this is always wrong with any of the AyaNova business objects:
Client c=new Client();  <----WRONG!

Instead use one of the static / shared methods, for example:
Client c = Client.GetItem(ID);  or Client c = Client.NewItem();

Programming with each AyaNova business object type

CRUD
All of the business objects support one or more of the following general methods: Create, Retrieve, Update and Delete.

Read only object 
•	Retrieve - A read only object is retrieved through it's Static / Shared GetItem(Guid ID) or similar method.  Some objects have convenience overloads for GetItem or have a slightly different named get method like "GetList" or "GetListForOneItem" etc.

Read only collection object
•	Retrieve - There are two sub types of read only collection objects used throughout AyaNova, the ones with names that end in "List" are generally used with DataGrids in the AyaNova UI and have a GetListByCriteria(string xmlCriteria) method where the xmlCriteria is a fragment of XML that specifies the criteria and order by specifications for the underlying query.  xmlCritiera can be left empty to just get the whole list and this is generally how you would do it unless using one of the overloads for a specified list of ID's or single item.
•	Generally the "List" objects are not used for any purpose but display in a grid but they can be very handy for getting nicely formatted information about business objects that goes beyond what is stored inside the object itself.  The second sub type of Read Only Collection objects generally end in the name "PickList" and are used to provide a working list with the name, id and active status of objects as well as selected additional fields that are specific to that object.  These types of objects generally implement a shared / static GetList() method although some objects have alternative GetList type methods allowing limited filtering. 

Editable root object
•	Create - A new editable root object is created through it's Static / Shared NewItem() method.  It is not saved to database until the Save() method is called on it. NewItem() only creates an in-memory object that doesn't physically exist or is visible to other AyaNova users until the Save() method is called. Every editable root object in AyaNova is identified by a Guid field called "ID".  This value is set by the business object when it's created and can not be set or changed by the user.  
•	Update - Editable root objects have various properties defined that can be set.  Each property may have one or more business rules that will be enforced when the property is set.  For example a Unit object requires a serial number.  If you try to save it without setting the serial number it will fail.  You can always see if an object can be saved by checking the IsSavable property and you can tell what rules are broken by checking the contents of the BrokenRulesText property. VERY IMPORTANT: The Save() method returns a fresh copy of the object after saving.  If you intend to keep using the object after saving it then you must set your variable for that object to the object returned by Save().  I.E.  Unit u=Unit.NewItem();  u.Serial="abc"; u=(Unit)u.Save(); Notice that the Save() method object returned is a generic one and needs to be cast to the type of object in question.  AyaNova uses a concurrency system that favors the first person to save a duplicate object.  When two people at different computers open the same object and both modify it and save it, the person that saved first "wins" and the second user's object will return an exception indicating that the object was already changed by another user including the user's name.  Your app should handle that situation.
•	Retrieve - Editable Root Objects are retrieved by the Shared / Static method GetItem(Guid ID);  In some rare cases there may be other GetXX methods implemented where it makes sense to do so.
•	Delete - Editable Root Objects can be deleted in two ways: By marking an instantiated object as Deleted by calling it's base Delete method (not recommended, may be deprecated in future, AyaNova does not use this method itself), or by calling the Shared / Static Delete(Guid ID) method (use this one).  
•	A delete is not guaranteed for any object and this should be anticipated.  For example a closed work order can not be deleted, the one and only Global object can not be deleted and in the case of an object that has relationships active in the database with other objects a delete will throw a database exception regarding referential integrity.  For example if a client is used on any workorders it can not be deleted until those workorders are removed or the client changed.  This is common for pretty much every editable root object and your application should handle this situation.

Editable child object
•	Create - Editable child objects that are part of a collection are created through their parent collections Add method.  For example a Rate object is not created directly but created by calling the Add() method on the parent Rates collection which in turn is generally a field in another object.  In some cases editable child objects are not part of a collection but are a single object contained in a field within a parent object.  In those cases the child is created by default by the parent object and does not need to be created by the developer as it already exists.  A good example of this is an Address in a Client object.  You don't need to create one, it's always there and created by the Client when it is in turn created.
•	Update - Editable child objects are updated by retrieving them via an indexer for their collection or a property on their parent object that represents them.  For example a service rate in a contract's rates collection is retrieved by ID by the indexer in Rates contract.Rates[ID].   Various indexers are implemented for all collections including a simple index by position.   Editable child objects are saved  via their parent object or collection object they reside in.  Generally speaking you only save the highest parent object in the hiearchy, never a child collection directly.  So for example a Contract object has a child Rates collection which in turn has individual service rates for that contract.  You would only ever save the Contract which in turn will save the child collection which will in turn save the Child rate objects automatically.
•	Retrieve - An editable child is retrieved by retrieving it's parent object.  In the Contract example previously, you don't retrieve an individual rate, you retrieve the contract which in turn retrieves the Rates collection which in turn retrieves the individual rates.  
•	Delete - An editable child is deleted by removing it from the collection it is contained in by calling the collection's Remove method and then saving the collection via it's parent to make the change in the actual database.  A deleted child object in a collection is not physically deleted from the database until it's parent collection is saved.  A child object that exists in a one to one relationship with another object (i.e. is not part of a collection) can not be deleted unless the entire parent object is deleted.

Editable child collection object
•	All methods for these objects are pretty much covered in the Editable child subject above.  It's important to note that these objects are always a field within a parent object.
•	
•	Editable Root Collection object
•	Create - There is no need to ever create an entire editable root collection, it is always present and is worked with by retrieving the one and only editable root collecton.
•	Update - Editable root collections are not directly edited, they are a container to hold editable child objects which are edited via the root collection indirectly.
•	Retrieve - Editable root collections are retrieved via their Shared / Static GetItems() method and various alternatives.  It should be noted that even if you know you have no items of a particular type present in the database, let's say PartWarehouses as an example, you would still call the GetItems() method before you can add a PartWarehouse to it's collection.
•	Delete - An editable root collection is never deleted wholesale, it's child items that it contains can be deleted by calling the collection object's Remove method for individual child items

Sample projects

The sample projects were created in Microsoft Visual Studio 2008.  

Exceptions

If your application should receive an exception error while using the AyaNova business objects please note that more often than not the exception you will receive is a TargetInvocation exception.  

To get the actual exception you need to use the InnerException property of the initial exception.  This is because the AyaNova objects are invoked indirectly by a factory method and it wraps the original exception in a TargetInvocation Exception.

Your debugger output window will most likely show the entire exception, but if you want to report it to a user, make sure you “crack” the exception returned by looping through it and getting every inner exception within each exception level by level. The HelloAyaNova example shows how to do this.
It’s possible that the first level will be relevant, more likely the second level is more relevant and in some cases such as a database generated exception they will be in a third level deep.

If you see a TargetInvocation exception it is generally meaningless and won’t help you diagnose the problem, you need the inner exception to get the real error.

Questions

Please do not hesitate to post your questions on the AyaNova developer support forum at forum.ayanova.com  This forum is monitored by our developers and questions will often be answered the same day.  Remember we support the AyaNova api only, we can not write your program for you or provide help with 3rd party tools etc where other means of support exist.