ayanova7/doc/Content/AyaScript for AyaNova plugin.aml

<?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>