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.
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.
Scripts are available from within the AyaNova AyaScript plugin menu from anywhere in AyaNova that you specify.
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.
Example scripts are provided to get you started
AyaScript is also useful for AyaNova support to provide end users with snippets of code to resolve unique problems in a timely manner
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
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.
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.
Generated assemblies are cached so there is no performance penalty for scripts that are executed repeatedly.
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.
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.
AyaScript supports c# only, other development languages are not supported.
Users will need to be experienced in .net development to use AyaScript
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.
AyaScript is potentially dangerous - 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. There is no safety net. 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
Set up a safe environment to test development: Use a copy of your database, or download and install the trial version of AyaNova along with a sample database.
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.
Once you have a safe development environment set up, download and install the free AyaScript plugin from the AyaNova plugin's page.
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->Open and choose the script you want to see the source code for.
AyaScripts consist of two sections, the header and main body.
Header - 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.
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
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->Header menu option in AyaScript.
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.
Header line: //Script created: - 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.
Header line: //Name: - 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->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.
Header line: //ShowInMenuFor: - 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
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.
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.
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.
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 selected 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.
Header line: //HandlesAyaNovaTypes: - 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.
Body - 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.
Comments / Includes / stuff at the top - 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:
AyaScriptMain - The main entry point for your script. Required to be present with the exact method signature and parameters like this:
public static void AyaScriptMain(bool IsList, RootObjectTypes objectType, Object ayaNovaObject, List
Will be true if script was called from a list form.
AyaNova RootObjectType of passed ayaNovaObject or the type of object in the list if it's a list object
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".
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.
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. Review questions on our AyaNova Development / SDK / API section of the AyaNova support forum, and contact us directly if any questions.
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 AyaNova Development / SDK / API section of the AyaNova support forum. As we get more samples we'll likely open up a specific area for sample code.
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:
AyaNova