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

361
doc/Content/AyaScript for AyaNova plugin.aml Normal file
View File

@@ -0,0 +1,361 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="572b9fe6-e499-4cae-a144-3048b6849667" revisionNumber="1">
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>AyaScript is a useful utility for testing and running snippets of C# code against the AyaNova developers API</para>
</introduction>
<!-- start header -->
<section><!--H1-->
<title><mediaLink><image xlink:href="AyaNova_Service_Management_Software_Logo" /></mediaLink>
AyaScript for AyaNova</title>
<content><!-- end header --><!-- start page -->
<!-- start content -->
</content>
</section>
<section><!--H2-->
<title>Harness the power of the AyaNova API from within AyaNova!</title>
<content>
<para>Create and execute c# code directly from the AyaNova plugin menu. </para>
</content>
</section>
<section><!--H3-->
<title>About AyaScript </title>
<content><mediaLink><image xlink:href="Script128" /></mediaLink>
<para>AyaScript provides an editor and runtime environment to develop and execute
your own c# code using the AyaNova API and any other resources of the .net
framework.</para>
<para>The cool thing about AyaScript is it's quick, easy and everything is provided
to build and execute your code without requiring any other programs or utilities
such as a development environment.</para>
<para>Scripts are available from within the AyaNova AyaScript plugin menu from
anywhere in AyaNova that you specify.</para>
<para>This means you can quickly create useful utilities or Add-on's without having
to build a full AyaNova plugin or stand alone application and your end users can
execute the script from within the AyaNova program without any programming
knowledge.</para>
<para>Example scripts are provided to get you started</para>
<para>AyaScript is also useful for AyaNova support to provide end users with
snippets of code to resolve unique problems in a timely manner</para>
<para>Since AyaScript code is standard c# code any code developed in AyaScript can
easily be turned into a separate AyaNova plugin or stand alone program that uses
the AyaNova API</para>
</content>
</section>
<section><!--H3-->
<title>How it works </title>
<content>
<para>Scripts are written in standard c# code and have access to the full AyaNova
API and AyaNova business object or list of objects that a user selects in
AyaNova.</para>
<para>When a script is selected to execute by the end user the relevant objects
from the AyaNova application are passed to the script and it's compiled and an
assembly is generated and executed on the fly.</para>
<para>Generated assemblies are cached so there is no performance penalty for
scripts that are executed repeatedly.</para>
<para>Scripts are plain text and everything required to run them is stored in one
text "file" so you can easily move them and share them with others.</para>
<para>All scripts are stored in an xml file (AyaScripts.xml) in the AyaScript
plugin folder in the AyaNova program files folder. You do not need to work
directly with this file as the AyaScript Editor handles all script persistence
and all information required for a script to execute is stored in the text of
the script itself.</para>
</content>
</section>
<section><!--H3-->
<title>Dangers and Limitations </title>
<content>
<para>AyaScript supports c# only, other development languages are not
supported.</para>
<para>Users will need to be experienced in .net development to use AyaScript</para>
<para>We do not provide support for development questions, however we will answer
questions regarding the AyaNova API itself. In other words we can not teach you
how to program but we will be happy to answer questions about using the AyaNova
API on the development support forum.</para>
<para><legacyBold>AyaScript is potentially dangerous</legacyBold> - it allows you to do anything you
can do in the AyaNova program but a million times more quickly so it's very easy
to damage your data. <legacyBold>There is no safety net.</legacyBold> For this reason we recommend
in the strongest possible terms that you develop your scripts on a trial
database or a copy of your live data and test thoroughly before you even
consider making the script available to your live data users</para>
</content>
</section>
<section><!--H3-->
<title>Getting started </title>
<content>
<para>Setup a safe environment to test development: Use a copy of your database or
download an install the trial version of AyaNova</para>
<para>We recommend doing development work in a virtual machine. In fact all AyaNova
development we do here is within virtual machines, there are many benefits to
doing so. We use VMWare Workstation for our own developers however we have also
tried the free Virtual Box utility and it is sufficient for AyaNova development
though not as fast in our experience. Developing in a virtual machine means you
can safely isolate your testing and development from your live AyaNova and a
virtual machine can be easily backed up and transported between hardware
platforms if your computer should "crater" meaning little or no down time.</para>
<para>Once you have a safe development environment set up, download and install the
free AyaScript plugin from the AyaNova plugin's page.</para>
<para>Run AyaNova and select the AyaScript plugin, you will see several sample
scripts. To view the code for them select the first option which is always the
AyaScript Editor. Select Script-&gt;Open and choose the script you want to see
the source code for.</para>
</content>
</section>
<section><!--H3-->
<title>Script HEADER section format </title>
<content>
<para>AyaScripts consist of two sections, the header and main body.</para>
<para><legacyBold>Header</legacyBold> - The header contains c# single line style comments that are
instructions to the AyaScript processor telling it when and where to show the
script menu option to the end user and also the name of the script to display in
the menu.</para>
<para>The header section is *required*, if any part of it is missing or malformed
or doesn't pass a "sanity" check your script will not run or will not be
available. Use the Header builder tool to ensure your script is compliant</para>
<para>AyaScript editor comes with a Header builder tool to automate the process of
setting up the header section correctly, you can use the header builder at any
time to create or edit the header or once you become more familiar with the
header format you can simply type in the options. The header builder is
available from the Edit-&gt;Header menu option in AyaScript.</para>
<para>Note that the header builder displays all possible object types in AyaNova
defined in the RootObjectTypes enumerator in the AyaNova business object
library; at present not all types listed are supported from the plugin menu as
there is either no editor for them in the AyaNova program or they are not an
editable type. However all the main Root object types in AyaNova that your users
are generally concerned with are supported. We've provided all of them as we may
add editors for other types in future through a future update to the AyaNova
program itself.</para>
<para>Header line: <legacyBold>//Script created:</legacyBold> - This is not a required line, it's
simply a convenience that is added by the header builder when a new script is
created, you can delete it if you don't want it there.</para>
<para>Header line: <legacyBold>//Name:</legacyBold> - This is required. When a new script is created
using the new script command it's set to the current date and time however you
can edit it to whatever you want. This is the text displayed to the end user in
the AyaScript-&gt;scripts list. Ideally it should be unique but AyaScript won't
explode if you accidentally name two the same as internally it generates a
unique Guid for each script when they are loaded and uses that instead of the
name.</para>
<para>Header line: <legacyBold>//ShowInMenuFor:</legacyBold> - This is required. This controls in
what situations AyaScript will offer the script to the end user in the menu.
Your choices are Everywhere, Main menu only, Single AyaNova object, List of
AyaNova objects</para>
<para>
<list class="bullet"><legacyUnderline>Show in menu for</legacyUnderline>
<listItem>Everywhere</listItem>
<para>Show regardless of where the AyaNova user is in the AyaNova user interface.
Generally this would be for utilities that are not tied to a specific business
object, for example our Screenshot script, however the list or single object
*is* passed to the script so this could also be for scripts that are designed
to work with any object.</para>
<listItem>Main menu only</listItem>
<para>Only show from the main menu plugin menu item. This is generally used for
utilities that are not designed to work with a specific business object and
indeed when a script is called from the main menu no object is passed to the
script since there isn't one and the object type is set to nothing.</para>
<listItem>Single AyaNova object</listItem>
<para>Only show from the single object editing form and only for the object types
specified in the //HandlesAyaNovaTypes: (detailed below). For example you may
want a script to only be available when in the client entry form or the work
order entry form. This option specifically excludes offering the script in the
menu when the user is viewing a list of AyaNova objects in the user
interface.</para>
<listItem>List of AyaNova objects</listItem>
<para>Only offer the script in the AyaScript plugin menu when the user is viewing
a list of AyaNova objects (i.e. the main form right window). For example if
the user selects clients (or units or vendors or workorders etc etc) in the
left side navigation window and a list of clients is displayed in the right
pane. Note that when a script is selected from a list like this, the ID list
contains only the objects <legacyBold>selected</legacyBold> by the end user so if a user want's
to apply your script to objects in the list they need to select them first.
That being said the underlying list object *is* passed to the script so you
can iterate all the items in the list yourself if none are selected and in
fact many of our plugins work that way on the assumption that if a user hasn't
specficially selected one or more objects then their intention is to apply the
plugin to *all* the objects in the list.</para></list>
<para></para>
<para>Header line: <legacyBold>//HandlesAyaNovaTypes: </legacyBold>- This is required. This controls
which object types you want your script to be shown for. This is the text of the
RootObjectTypes enumeration in the AyaNova API. Use the script header builder to
easily choose the root object types you want to support and ensure they are
spelled correctly. Your script can handle more than one type however if it does
you will need to check the type of the object passed and cast it accordingly.
Generics can be helpful here though scripts are so quick and easy you might find
it easier to simply copy and paste your script and change accordingly for the
different object types. For example if you have a script to process a Client and
want to do the same with a HeadOffice it might be simpler and quicker to simply
copy the script and change the object types in it rather than adding a switch
statement and replicating the same code in one script. Note as stated earlier:
*all* AyaNova RootObjectTypes are listed however not all are suppored by the
AyaNova plugin system. Some are not real objects edited by the end user and some
just don't have an interface for editing alone, however we've left all in
because future updates of AyaNova may contain support for more objects. The easy
way to tell if an object you want to work with is supported is simply run
AyaNova go the the form where you can edit or view that object and see if the
plugin menu option is displayed in the menu at the top. If it is, that object
type is supported and you can work with it in your script. At present pretty
much every object of any consequence is supported.</para></para></content>
</section>
<section><!--H3-->
<title>Script main body section format </title>
<content>
<para><legacyBold>Body</legacyBold> - The body of scripts consists of standard c# code. There is one
required method (AyaScriptMain) and the rest is up to you. You can add other
methods, other classes, includes etc as long as you include the required
AyaScriptMain method. Think of the AyaScriptMain method as the equivalent of a
Main method in a c# console application. It's the method that AyaScript expects
to be there and calls with set parameters. </para>
<para><legacyBold>Comments / Includes / stuff at the top</legacyBold> - You can specify anything you
want above the AyaScriptMain method. Remember this is standard c# so you can use
multiline style comments /*comment*/ or single line comments //. You can also
use include statements to save typing. Note that AyaScript automatically inserts
include statements for you just before compiling the code, this is provided as a
convenience, however if you specify the same include AyaScript is smart enough
to know not to add it again and won't. The automatically inserted includes are:
<list class="bullet">
<listItem>System.Collections.Generic</listItem>
<listItem>System.Data</listItem>
<listItem>System.Drawing</listItem>(Note: System.Drawing.Region conflicts with the AyaNova
business object Region so you must fully qualify like this:
GZTW.AyaNova.BLL.Region)
<listItem>System.Text</listItem>
<listItem>System.Windows.Forms</listItem>
<listItem>GZTW.AyaNova.BLL</listItem>
<listItem>AyaNova.PlugIn.AyaScript</listItem>(Used for predefined forms we may add from
time to time. Initially there is one CopyableMessageBox form included see the
sample for details) </list>
<para></para>
<para><legacyBold>AyaScriptMain</legacyBold> - The main entry point for your script. Required to be
present with the exact method signature and parameters like this: </para>
<code language="C#">public static void AyaScriptMain(bool IsList, RootObjectTypes objectType, Object ayaNovaObject, List objectIDList)
{
MessageBox.Show("Hello from AyaScript!");
} </code>
<definitionTable>
<definedTerm>IsList</definedTerm>
<definition>Will be true if script was called from a list form.</definition>
<definedTerm>objectType</definedTerm>
<definition>AyaNova RootObjectType of passed ayaNovaObject or the type of object in the
list if it's a list object</definition>
<definedTerm>ayaNovaObject</definedTerm>
<definition>If a single object then this is the AyaNova business object, if a list then
this is the list object, if called from the main menu where there is no object
this is DBNull.Value. Note: this is never simply "null".</definition>
<definedTerm>objectIDList</definedTerm>
<definition>If a list, this contains the id's of the AyaNova objects which the end user
has *selected* in the list, otherwise it's an empty list. If IsList is true
and this list is empty it means the user selected your script from a list but
hasn't selected any items in the list. You can either warn them about this or
treat it as an intention to apply your script to all objects in the list in
which case you can get access to the entire list through the ayaNovaObject
parameter which will be the underlying list object itself.</definition>
</definitionTable>
</para>
</content>
</section>
<section><!--H3-->
<title>Support / API documentation / Share scripts </title>
<content>
<para><legacyBold>Support</legacyBold> - As stated previously, while we cannot teach you how to
program we are happy to provide help with specific problems using the AyaNova
API itself. Post your questions to the <externalLink>
<linkText>AyaNova Development / SDK / API section</linkText>
<linkUri>http://forum.ayanova.com/forumdisplay.php?42-Development-SDK-API</linkUri>
</externalLink> of the AyaNova support forum. </para>
<para><legacyBold>Share your scripts</legacyBold> - If you've come up with a handy script you'd like
to share with others copy and paste it into a post in the development area of
our support forum. As we get more samples we'll likely open up a specific area
for sample code.</para>
</content>
</section>
<section><!--H2-->
<title>Handy links</title>
<content>
<list class="bullet">
<listItem>AyaNova Development / API / SDK <externalLink>
<linkText>support forum</linkText>
<linkUri>http://forum.ayanova.com/forumdisplay.php?42-Development-SDK-API</linkUri>
</externalLink></listItem>
<listItem>AyaNova API <externalLink>
<linkText>documentation</linkText>
<linkUri>http://api.ayanova.com/</linkUri>
</externalLink></listItem>
<listItem>Download <externalLink>
<linkText>AyaNova Plugins</linkText>
<linkUri>http://www.ayanova.com/plugins.htm</linkUri>
</externalLink> including AyaScript</listItem>
<listItem>c# language <externalLink>
<linkText>specifications</linkText>
<linkUri>http://msdn.microsoft.com/en-us/library/aa645596(VS.71).aspx</linkUri>
</externalLink></listItem>
<listItem><externalLink>
<linkText>Stack Overflow</linkText>
<linkUri>http://stackoverflow.com/</linkUri>
</externalLink>
questions and answers for programmers</listItem>
<listItem><externalLink>
<linkText>CodeProject.com</linkText>
<linkUri>http://www.codeproject.com/</linkUri>
</externalLink>
- questions answers and articles for programmers</listItem></list>
</content>
</section>
<section><!--H2-->
<title>Free development environments</title>
<content>
<para>While an integrated development environment is not required to work with
AyaScript it can be useful to have an ide on hand to get the syntax and
spelling correct for more complex scripts. We use Visual Studio Professional
in-house however there are a couple of free alternatives available:</para>
<list class="bullet">
<listItem>Microsoft® Visual C#® 2008 <externalLink>
<linkText>Express Edition</linkText>
<linkUri>http://www.microsoft.com/express/Windows/</linkUri>
</externalLink></listItem>
<listItem><externalLink>
<linkText>#develop</linkText>
<linkUri>http://www.icsharpcode.net/OpenSource/SD/</linkUri>
</externalLink> (short for SharpDevelop) is a free, open source
IDE for C#</listItem></list>
</content>
</section>
<section><!--H2-->
<title>Special thanks</title>
<content>
<para>AyaScript uses the excellent <externalLink>
<linkText>CS-Script</linkText>
<linkUri>http://csscript.net/</linkUri>
</externalLink>© script execution engine by Oleg
Shilo.</para><!-- end sidebar -->
&#160;<!-- end page -->
</content>
</section>
<relatedTopics>
</relatedTopics>
</developerConceptualDocument>
</topic>

334
doc/Content/QuickStart.aml Normal file
View File

@@ -0,0 +1,334 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="572b9fe6-e499-4cae-a144-3048b6849668" revisionNumber="1">
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>This is a quick start guide to the AyaNova business object API for experienced developers.</para>
<para><alert class="note">If you have any questions after reading this guide and examining the sample applications
we will be happy to answer them on the <externalLink><linkText>AyaNova Development / SDK / API forum.</linkText>
<linkUri>http://forum.ayanova.com/forumdisplay.php?42-Development-SDK-API</linkUri>
</externalLink> </alert>
</para>
</introduction>
<section>
<title>About</title>
<content>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>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 <externalLink><linkText>good article</linkText><linkUri>http://en.wikipedia.org/wiki/.NET_Framework</linkUri></externalLink> on Wikipedia about it. </para>
</content>
</section>
<section>
<title>What kind of program can I write?</title>
<content>
<para>Every AyaNova related program, add-on and plugin we offer was written using this AyaNova API.</para>
<para>You have several choices for the type of application you develop with the AyaNova API:
<list class="ordered">
<listItem>Stand alone windows application (like AyaNova itself or our Generator windows service)</listItem>
<listItem>ASP.NET web application (like our <externalLink><linkText>WBI / MBI</linkText><linkUri>http://www.ayanova.com/remote_access_field_service.htm</linkUri></externalLink> optional add-ons)</listItem>
<listItem>AyaNova Plugin (like our <externalLink><linkText>AyaNova plugins</linkText><linkUri>http://www.ayanova.com/plugins.htm</linkUri></externalLink>)</listItem>
<listItem>AyaScript "macro" (<externalLink><linkText>a free AyaNova plugin</linkText><linkUri>http://www.ayanova.com/plugins.htm#AyaScript</linkUri></externalLink> that can run an easy to distribute (copy and paste text) snippet of c# code inside AyaNova itself)</listItem>
<listItem>Anything that supports .net - you can now access .net code from virtually any development environment so there are really no limitations</listItem>
</list>
</para>
</content>
</section>
<section>
<title>Requirements</title>
<content>
<para>To develop an application that can work with the AyaNova business object library you need the following:
<list class="bullet">
<listItem>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.
</listItem>
<listItem>Internet access to the online <externalLink><linkText>AyaNova API documentation</linkText><linkUri>http://api.ayanova.com</linkUri></externalLink> in the section AyaNova Business Object Library </listItem>
<listItem>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
<para>Here are some free ones:</para>
<list class="bullet">
<listItem><externalLink><linkText>Microsoft Visual Studio Express</linkText><linkUri>http://www.microsoft.com/express/</linkUri></externalLink></listItem>
<listItem><externalLink><linkText>Sharp Develop</linkText><linkUri>http://www.sharpdevelop.net/OpenSource/SD/Default.aspx</linkUri></externalLink></listItem>
<listItem><externalLink><linkText>AyaScript AyaNova plugin</linkText><linkUri>http://www.ayanova.com/plugins.htm#AyaScript</linkUri></externalLink></listItem>
</list>
</listItem>
</list></para>
</content>
</section>
<section>
<title>Distributing your program</title>
<content>
<para>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.</para>
<para>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.</para>
</content>
</section>
<section>
<title>Royalties? License fees? What does it cost me to develop for AyaNova?</title>
<content>
<para>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.</para>
<para>You may use the API to develop applications for in-house, private or for profit commercial purposes.</para>
</content>
</section>
<section>
<title>Integrating other applications with AyaNova</title>
<content>
<para>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 <externalLink><linkText>AyaNova API documentation</linkText><linkUri>http://api.ayanova.com</linkUri></externalLink> and have a look at the objects that start with the word "Integration" for more details.</para>
</content>
</section>
<section>
<title>Programming languages supported</title>
<content>
<para>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:</para>
<list class="bullet">
<listItem>C#</listItem>
<listItem>Visual Basic .Net</listItem>
<listItem>C++/CLI</listItem>
<listItem>J# (java for .net) </listItem>
<listItem>F#</listItem>
<listItem>And <externalLink><linkText>many many more</linkText><linkUri>http://en.wikipedia.org/wiki/CLI_Languages</linkUri></externalLink>. </listItem>
</list>
<para>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.</para>
</content>
</section>
<section>
<title>Getting started step by step</title>
<content>
<alert class="caution">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.
</alert>
<para>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.
</para>
<para><alert class="note">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.</alert>
</para>
<list class="ordered">
<para>These are the steps to follow to get your project started:</para>
<listItem><externalLink><linkText>Download</linkText><linkUri>http://www.ayanova.com/download.htm</linkUri></externalLink> 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.
</listItem>
<listItem>Create your initial empty project in the language and development environment of your choice</listItem>
<listItem>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:
<list class="bullet">
<listItem>GZTW.AyaNova.BLL.dll</listItem>
<listItem>GZTW.Data.dll</listItem>
<listItem>GZTW.Profile.dll</listItem>
<listItem>CSLA.dll</listItem>
<listItem>CSLA.Server.DataPortal.dll</listItem>
<listItem>CSLA.Core.Bindablebase.dll</listItem>
</list>
</listItem>
<listItem>Add a reference to the .net Firebird database driver in the AyaNova installation folder:
<list class="bullet">
<listItem>FirebirdSql.Data.FirebirdClient.dll</listItem>
</list> </listItem>
<listItem>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:
<list class="bullet">
<listItem>fbembed.dll</listItem>
<listItem>firebird.msg</listItem>
<listItem>cudt30.dll</listItem>
<listItem>icuin30.dll</listItem>
<listItem>icuuc30.dll</listItem>
</list> </listItem>
<listItem>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.
</listItem>
<listItem>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.
</listItem>
</list>
<alert class="security">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.</alert>
</content>
</section>
<section>
<title>Windows Vista / Windows 7 / newer</title>
<content>
<para>The AyaNova business object library is fully compatible with all modern versions of Windows.</para>
<para>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.
</para>
<para>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. :)
</para>
<para>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.
</para>
</content>
</section>
<section>
<title>About the AyaNova business objects</title>
<content>
<para>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:</para>
<definitionTable>
<definedTerm>Read only</definedTerm>
<definition>Single object that generally is used internally by AyaNova to retrieve a count or a name or check for the existance of an object.</definition>
<definedTerm>Read only collection</definedTerm>
<definition>Collection of objects generally used for display lists (main grid lists) or selection like a ClientPickList.</definition>
<definedTerm>Editable Root</definedTerm>
<definition>Single object that can be modified and saved. Typically these represent a real world object in AyaNova like a Client or a Workorder.</definition>
<definedTerm>Editable Child</definedTerm>
<definition>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.
</definition>
<definedTerm>Editable Child Collection</definedTerm>
<definition>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.
</definition>
<definedTerm>Editable Root Collection</definedTerm>
<definition>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.
</definition>
</definitionTable>
<alert class="important">
<para><legacyBold>Without exception</legacyBold>, every AyaNova business object is retrieved or created using a shared / static method of that object, <legacyBold>never by direct instantiation</legacyBold>.
</para>
<para>
For example, this is always wrong with any of the AyaNova business objects:
<codeInline>Client c=new Client(); <legacyBold>&lt;----WRONG!</legacyBold></codeInline>
</para>
<para>
Instead use one of the static / shared methods, for example:
<codeInline>Client c = Client.GetItem(ID); or Client c = Client.NewItem(); <legacyBold>&lt;----RIGHT!</legacyBold></codeInline>
</para>
</alert>
</content>
</section>
<section>
<title>Programming with each AyaNova business object type
</title>
<content>
<para><legacyBold>C.R.U.D.</legacyBold> - All of the business objects support one or more of the following general method patterns: <newTerm>Create</newTerm>, <newTerm>Retrieve</newTerm>, <newTerm>Update</newTerm> and <newTerm>Delete</newTerm>.
</para>
<para><legacyBold>Read only object</legacyBold></para>
<list class="bullet">
<listItem><legacyBold>Retrieve</legacyBold> - A read only object is retrieved through it's Static / Shared <codeInline>GetItem(Guid ID)</codeInline> or similar method. Some objects have convenience overloads for GetItem or have a slightly different named get method like "GetList" or "GetListForOneItem" etc.
</listItem>
</list>
<para><legacyBold>Read only collection object</legacyBold></para>
<list class="bullet">
<listItem><legacyBold>Retrieve</legacyBold> - 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 <codeInline>GetListByCriteria(string xmlCriteria)</codeInline> 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.
</listItem>
<listItem>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.</listItem>
</list>
<para><legacyBold>Editable root object</legacyBold></para>
<list class="bullet">
<listItem><legacyBold>Create</legacyBold> - A new editable root object is created through it's Static / Shared <codeInline>NewItem()</codeInline> method. It is not saved to database until the <codeInline>Save()</codeInline> method is called on it. <codeInline>NewItem()</codeInline> only creates an in-memory object that doesn't physically exist or is visible to other AyaNova users until the <codeInline>Save()</codeInline> method is called. Every editable root object in AyaNova is identified by a Guid field called <literal>ID</literal>. This value is set by the business object when it's created and can not be set or changed by the user.
</listItem>
<listItem><legacyBold>Update</legacyBold> - 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 <codeInline>IsSavable</codeInline> property and you can tell what rules are broken by checking the contents of the <codeInline>BrokenRulesText</codeInline> property.
<alert class="important">
<para>The <codeInline>Save()</codeInline> method returns a fresh copy of the object after saving. <legacyBold>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 <codeInline>Save()</codeInline></legacyBold>. I.E. <codeInline>Unit u=Unit.NewItem(); u.Serial="abc"; u=(Unit)u.Save(); </codeInline> Notice that the <codeInline>Save()</codeInline> method object returned is a generic one and needs to be cast to the type of object in question.
</para>
</alert>
<alert class="important">
<para>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.</para>
</alert>
</listItem>
<listItem><legacyBold>Retrieve</legacyBold> - Editable Root Objects are retrieved by the Shared / Static method <codeInline>GetItem(Guid ID);</codeInline> In some cases there may be other GetXX methods implemented for special cases.
</listItem>
<listItem><legacyBold>Delete</legacyBold> - 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 <codeInline>Delete(Guid ID)</codeInline> method (use this one).
<alert class="note">
<para>
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.
</para>
</alert>
</listItem>
</list>
<para><legacyBold>Editable child object</legacyBold></para>
<list class="bullet">
<listItem><legacyBold>Create</legacyBold> - Editable child objects that are part of a collection are created through their parent collections <codeInline>Add</codeInline> method. For example a Rate object is not created directly but created by calling the <codeInline>Add()</codeInline> 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.
</listItem>
<listItem><legacyBold>Update</legacyBold> - 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 <literal>ID</literal> by the indexer in Rates <codeInline>contract.Rates[ID]</codeInline>. 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. </listItem>
<listItem><legacyBold>Retrieve</legacyBold> - 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.</listItem>
<listItem><legacyBold>Delete</legacyBold> - 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.</listItem>
</list>
<para><legacyBold>Editable child collection object</legacyBold></para>
<list class="bullet">
<listItem>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.</listItem>
</list>
<para><legacyBold>Editable Root Collection object</legacyBold></para>
<list class="bullet">
<listItem><legacyBold>Create</legacyBold> - 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.</listItem>
<listItem><legacyBold>Update</legacyBold> - Editable root collections are not directly edited, they are a container to hold editable child objects which are edited via the root collection indirectly.</listItem>
<listItem><legacyBold>Retrieve</legacyBold> - Editable root collections are retrieved via their Shared / Static <codeInline>GetItems()</codeInline> 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 <codeInline>GetItems()</codeInline> method before you can add a PartWarehouse to it's collection.</listItem>
<listItem><legacyBold>Delete</legacyBold> - 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.</listItem>
</list>
</content>
</section>
<section>
<title>Sample projects</title>
<content>
<para>The sample projects were created in Microsoft Visual Studio 2008</para>
<para>All samples are self extracting archives</para>
<para></para>
<para></para>
<list class="bullet">
<listItem>C# stand alone windows executable sample project <externalLink><linkText>CSHelloAyaNova.exe</linkText>
<linkUri>http://api.ayanova.com/files/CSHelloAyaNova.exe
</linkUri>
</externalLink>
</listItem>
<listItem>Visual Basic .Net stand alone windows executable sample project <externalLink><linkText>VBCreatePart.exe</linkText>
<linkUri>http://api.ayanova.com/files/VBCreatePart.exe
</linkUri></externalLink>
</listItem>
<listItem>C# AyaNova plugin sample project <externalLink><linkText>CSSamplePlugin.exe</linkText>
<linkUri>http://api.ayanova.com/files/CSSamplePlugin.exe
</linkUri></externalLink>
</listItem>
<listItem>Visual Basic .Net plugin sample project <externalLink><linkText>VBSamplePlugin.exe</linkText>
<linkUri>http://api.ayanova.com/files/VBSamplePlugin.exe
</linkUri></externalLink>
</listItem>
</list>
</content>
</section>
<section>
<title>Exceptions and error handling</title>
<content>
<para>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.
</para>
<para>To get the actual exception you need to use the <literal>InnerException</literal> 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.
</para>
<para>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.</para>
<para>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.
</para>
</content>
</section>
<section>
<title>Questions?</title>
<content>
<para>Please do not hesitate to post your questions on the <externalLink><linkText>AyaNova Development / SDK / API forum.</linkText>
<linkUri>http://forum.ayanova.com/forumdisplay.php?42-Development-SDK-API</linkUri>
</externalLink>
</para>
<para>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.</para>
</content>
</section>
<relatedTopics>
</relatedTopics>
</developerConceptualDocument>
</topic>