admin/ayanova7
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Browse Source
This commit is contained in:
John Cardinal
2018-06-29 19:47:36 +00:00
commit be7f501333
3769 changed files with 1425961 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
API/Quickstart.rtf Normal file
View File

@@ -0,0 +1,189 @@
{\rtf1\ansi\ansicpg1252\deff0\deflang1033\deflangfe1033{\fonttbl{\f0\fswiss\fprq2\fcharset0 Arial;}{\f1\fnil\fcharset2 Symbol;}}
{\colortbl ;\red0\green0\blue0;}
{\*\generator Msftedit 5.41.15.1515;}\viewkind4\uc1\pard\nowidctlpar\b\f0\fs24 AyaNova business object library quick start guide\par
\par
\fs20 This is a quick start guide for experienced developers.\par
\par
If you have any questions \ul after reading this guide and examining the sample applications \ulnone we will be happy to answer them on the AyaNova development forum at http://forum.ayanova.com \par
\par
\par
About \par
\par
\b0 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.\par
\par
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.\par
\par
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.\par
\par
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\par
\par
\par
\b What kind of program can I write?\b0\par
\par
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.\par
\par
\par
\b Requirements\par
\b0\par
To develop an application that can work with the AyaNova business object library you need the following:\par
\par
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\rquote 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.\par
\par
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.\par
\par
A .net development tool. We use Visual Studio Professional from Microsoft, however, you can use anything that supports .net\par
Here are some free ones:\par
Microsoft Visual Studio Express - http://www.microsoft.com/express/\par
Sharp Develop - http://www.sharpdevelop.net/OpenSource/SD/Default.aspx\par
\par
Internet access to the online AyaNova API documentation at: http://api.ayanova.com\par
\par
\par
\b Distributing your program\par
\par
\b0 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. \par
\par
\par
\b Royalties, license fees, what does it cost me to develop for AyaNova\par
\b0\par
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. \par
\par
\par
\b Integrating other applications with AyaNova\par
\b0\par
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.\par
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.\par
\par
\b Programming languages supported\par
\par
\b0 The AyaNova business object library was coded to conform to .net Common Language Infrastructure standards and as such you should have no problem \par
using the .net framework language of your choice. We code primarily in C#, but that has no relevance on what language\par
you may choose to use, the AyaNova business objects are language agnostic, you can use any of the following:\par
C++ (managed, i.e. .net)\par
C#\par
Visual Basic .Net\par
J# - Java for .net\par
Or anything else that supports .net\par
\par
A complete list can be found here:\par
http://en.wikipedia.org/wiki/CLI_Languages\par
\par
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\par
almost identical when it relates to the AyaNova business objects.\par
\par
\par
\b In general\par
\b0\par
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.\par
\par
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.\par
\par
\par
\b Getting started step by step\par
\par
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.\par
\b0\par
\pard{\pntext\f1\'B7\tab}{\*\pn\pnlvlblt\pnf1\pnindent0{\pntxtb\'B7}}\nowidctlpar\fi-720\li720 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.\par
{\pntext\f1\'B7\tab}Create your initial empty project in the language and development environment of your choice\par
{\pntext\f1\'B7\tab}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 \par
{\pntext\f1\'B7\tab}Add a reference to the .net Firebird database driver in the AyaNova installation folder: FirebirdSql.Data.FirebirdClient.dll\par
{\pntext\f1\'B7\tab}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\par
{\pntext\f1\'B7\tab}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.\par
{\pntext\f1\'B7\tab}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.\par
{\pntext\f1\'B7\tab}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.\par
{\pntext\f1\'B7\tab}If you are writing a plugin you do not need to concern yourself with authentication.\par
\pard\nowidctlpar\par
\par
\par
\b Windows Vista / Windows 7\par
\b0\par
The AyaNova business object library is fully compatible with Windows Vista and Windows 7.\par
\par
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.\par
\par
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. :)\par
\par
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.\par
\par
\par
\par
\b About the AyaNova business objects\par
\par
\b0 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:\par
\pard{\pntext\f1\'B7\tab}{\*\pn\pnlvlblt\pnf1\pnindent0{\pntxtb\'B7}}\nowidctlpar\fi-720\li720\b Read only \b0 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\par
\b{\pntext\f1\'B7\tab}Read only collection \b0 objects - a collection of objects generally used for list used for display or selection like a ClientPickList\par
\b{\pntext\f1\'B7\tab}Editable Root \b0 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. \par
\b{\pntext\f1\'B7\tab}Editable Child \b0 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.\par
\b{\pntext\f1\'B7\tab}Editable Child Collection \b0 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.\par
\b{\pntext\f1\'B7\tab}Editable Root Collection \b0 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\par
\pard\nowidctlpar\par
\par
\b No direct instantiation\par
\b0\par
Without exception every AyaNova business object is retrieved or created using a shared / static method of that object, never by direct instantiation. \par
For example, this is always wrong with any of the AyaNova business objects:\par
Client c=new Client(); <----WRONG!\par
\par
Instead use one of the static / shared methods, for example:\par
Client c = Client.GetItem(ID); or Client c = Client.NewItem();\par
\par
\par
\par
\b Programming with each AyaNova business object type\par
\par
CRUD\b0\par
All of the business objects support one or more of the following general methods: \b Create\b0 , \b Retrieve\b0 , \b Update \b0 and \b Delete\b0 .\b\par
\par
Read only object \par
\pard{\pntext\f1\'B7\tab}{\*\pn\pnlvlblt\pnf1\pnindent0{\pntxtb\'B7}}\nowidctlpar\fi-720\li720 Retrieve \b0 - 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.\b\par
\pard\nowidctlpar\par
Read only collection object\par
\pard{\pntext\f1\'B7\tab}{\*\pn\pnlvlblt\pnf1\pnindent0{\pntxtb\'B7}}\nowidctlpar\fi-720\li720 Retrieve \b0 - 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 \cf1 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.\cf0\b\par
\cf1\b0{\pntext\f1\'B7\tab}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. \cf0\b\par
\pard\nowidctlpar\par
\cf1 Editable root object\par
\pard{\pntext\f1\'B7\tab}{\*\pn\pnlvlblt\pnf1\pnindent0{\pntxtb\'B7}}\nowidctlpar\fi-720\li720 Create \b0 - 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. \cf0\b\par
\cf1{\pntext\f1\'B7\tab}Update \b0 - 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. \ul\b 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(). \ulnone\b0 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.\cf0\b\par
\cf1{\pntext\f1\'B7\tab}Retrieve \b0 - 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.\cf0\b\par
\cf1{\pntext\f1\'B7\tab}Delete \b0 - 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). \cf0\b\par
\cf1\b0{\pntext\f1\'B7\tab}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.\cf0\b\par
\pard\nowidctlpar\par
\cf1 Editable child object\b0\par
\pard{\pntext\f1\'B7\tab}{\*\pn\pnlvlblt\pnf1\pnindent0{\pntxtb\'B7}}\nowidctlpar\fi-720\li720\cf0\b Create \b0 - 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.\b\par
{\pntext\f1\'B7\tab}Update \b0 - 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.\b\par
{\pntext\f1\'B7\tab}Retrieve \b0 - 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. \b\par
{\pntext\f1\'B7\tab}Delete \b0 - 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.\b\par
\pard\nowidctlpar\par
Editable child collection object\par
\pard{\pntext\f1\'B7\tab}{\*\pn\pnlvlblt\pnf1\pnindent0{\pntxtb\'B7}}\nowidctlpar\fi-720\li720\b0 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.\b\par
\pard{\pntext\f1\'B7\tab}{\*\pn\pnlvlcont\pnf1\pnindent0{\pntxtb\'B7}}\nowidctlpar\par
{\pntext\f1\'B7\tab}Editable Root Collection object\par
\pard{\pntext\f1\'B7\tab}{\*\pn\pnlvlblt\pnf1\pnindent0{\pntxtb\'B7}}\nowidctlpar\fi-720\li720 Create \b0 - 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.\b\par
{\pntext\f1\'B7\tab}Update \b0 - Editable root collections are not directly edited, they are a container to hold editable child objects which are edited via the root collection indirectly.\b\par
{\pntext\f1\'B7\tab}Retrieve \b0 - 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.\b\par
{\pntext\f1\'B7\tab}Delete \b0 - 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\b\par
\pard\nowidctlpar\par
\par
Sample projects\b0\par
\par
The sample projects were created in Microsoft Visual Studio 2008. \par
\par
\par
\b Exceptions\par
\par
\b0 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. \par
\par
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.\par
\par
Your debugger output window will most likely show the entire exception, but if you want to report it to a user, make sure you \ldblquote crack\rdblquote 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.\par
It\rquote 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.\par
\par
If you see a TargetInvocation exception it is generally meaningless and won\rquote t help you diagnose the problem, you need the inner exception to get the real error.\par
\par
\b Questions\par
\b0\par
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.\par
\par
\par
}