This is a quick start guide to the AyaNova business object API 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 / SDK / API forum.|
AyaNova is built using 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 on Wikipedia about it.
What kind of program can I write?
Every AyaNova related program, add-on and plugin we offer was written using this AyaNova API.
You have several choices for the type of application you develop with the AyaNova API:
- Stand alone windows application (like AyaNova itself or our Generator windows service)
- ASP.NET web application (like our WBI / MBI optional add-ons)
- AyaNova Plugin (like our AyaNova plugins)
- AyaScript "macro" (a free AyaNova plugin that can run an easy to distribute (copy and paste text) snippet of c# code inside AyaNova itself)
- Anything that supports .net - you can now access .net code from virtually any development environment so there are really no limitations
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.
- Internet access to the online AyaNova API documentation in the section AyaNova Business Object Library
- A .net development tool or your standard development tool / language that can access .net code. We use Visual Studio Professional from Microsoft, however, you can use anything that supports .net
Here are some free ones:
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.
If you are using AyaScript, distribution is a simple copy and paste of text so it's as easy as posting the text of your AyaScript "macro" online or emailing it to your users.
Royalties? License fees? What does it cost me to develop for AyaNova?
Nothing. Our business is with AyaNova and we think a free and open environment for 3rd party developers can only be a good thing for our customers.
You may use the API to develop applications for in-house, private or for profit commercial purposes.
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 AyaNova API documentation 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 (except for AyaScript which only supports C#), the AyaNova business objects are language agnostic, you can use any of the following:
- Visual Basic .Net
- J# (java for .net)
- And many many more.
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.
Getting started step by step
|This should go without saying, but we will say it anyway: do not develop an application against your live in-use AyaNova database. It's very easy to make massive changes to an AyaNova database in the blink of an eye through code and testing may require blowing away the database and replacing it. Mistakes are bound to happen. You do not want to be responsible for losing valuable company data.|
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.
|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 (default on a 32bit os is C:\Program Files\Ground Zero Tech-Works Inc\AyaNova) and selecting the 6 .dll files that make up the business object library and it's supporting components:
- Add a reference to the .net Firebird database driver in the AyaNova installation folder:
- 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:
- 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.
|Logging in: If you are writing a stand alone application then any 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 or using AyaScript you do not need to concern yourself with authentication.|
Windows Vista / Windows 7 / newer
The AyaNova business object library is fully compatible with all modern versions of Windows.
If your standalone application you are developing will be run on Windows Vista or newer 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 or newer 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 object types are:
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(); <----RIGHT!
Programming with each AyaNova business object type
C.R.U.D. - All of the business objects support one or more of the following general method patterns: 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. They are also useful for using complex filters to retrieve data just as you can filter lists in the grid using the AyaNova user interface. 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.
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 cases there may be other GetXX methods implemented for special cases.
- 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 by wrapping your delete code in an exception handler.
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 automatically when a new Client is 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 hierarchy, 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 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.
The sample projects were created in Microsoft Visual Studio 2008
All samples are self extracting archives
Exceptions and error handling
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 which contains the actual relevant error in the InnerException property.
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 to support remoting which 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 top level exception will be relevant, more likely though the second level is more relevant and in some cases such as a database generated exception they will be a third level deep.
Please do not hesitate to post your questions on the AyaNova Development / SDK / API forum.
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.