Evolution

From Sage Evolution SDK | Documentation Portal
Jump to: navigation, search


Requirements

The following is required to get started with the SDK.

  • Runtime Environment : The Evolution SDK is deployed as a .net component library. As such you will require the Microsoft .NET framework ver. 2.0 or a compatible runtime to be installed wherever the component will be used. The SDK will also function in a Mono environment.
  • Registered Evolution Database including the SDK Connector Module : An Evolution database needs to be created and reachable before being able to utilise the SDK. The SDK does not operate at the UI level, purely at the database level. Please see Licensing below.
  • Developer Serial Number and Authorisation code : This Serial Number begins with DE and is issued when purchasing the Developer version of the SDK and the Authorisation code is issued by our registrations department against the Developer Serial Number. Please see Licensing below.


Create Your Project

Any .net project type may utilize the Evolution SDK natively; however a project with access to COM will also be able to utilize the component.

Adding a reference to the SDK component

  • .NET

When using a .NET IDE, to reference the dll merely involves opening your project and browsing to the location where you extracted the Pastel.Evolution.dll file.

  • COM

When using the API through its COM type library from Visual Basic 6 or earlier, Delphi, Office Macros etc., follow these steps to Register the SDK dll and reference the SDK tlb file: 

   *Ensure the .NET framework (at least version 2.0) is installed on the target machine.
   *Always only have one version of the Pastel SDK dll registered at a time.
   *Once registered do not move the location of the SDK dll.
   *Next, open a console window and change directory to the location of the SDK dll.
   *Add Pastel.Evolution.DLL to the .NET runtime's global assembly cache. This can be done by copying the DLL to %windir%\assembly. A utility, gacutil.exe is available in the .NET framework SDK for accomplishing 
    the same. Remember to have only one version of the dll registered at a time.
   *Use Regasm to register the dll by executing %windir%\Microsoft.NET\Framework\v2.0.50727\RegAsm.exe Pastel.Evolution.dll - note that your path may vary.
   *Now add a project reference to the .tlb file in the SDK directory.


Here is a sample batch file for registering the DLL: 

   gacutil.exe /uf Pastel.Evolution
   gacutil.exe /i Pastel.Evolution.dll
   RegAsm.exe /u Pastel.Evolution.dll
   RegAsm.exe Pastel.Evolution.dll

Notes: 

   *RegAsm and gacutil are shipped with the .NET Framework and .NET Framework SDK respectively.
   *Important: this procedure has to be repeated whenever you incorporate an SDK update into your project.
   *Furthermore, if you are making use of early binding facilitated by the more detailed .tlb generated by later version 5-compatible DLL's, you have to recompile your project whenever you update the SDK DLL.
   *You don't strictly need to have Pastel.Evolution.DLL in the GAC. It can also be used from your project's binary directory.
   *Do not have multiple versions of the SDK dll registered at the same time.
   *Do not move the location of the SDK dll after registering it.

Initialisation

Evolution runs of two SQL databases. The first is the Company/Client database which contains all the data that relates to the Company/Client. The second is the EvolutionCommon database that contains all of the registration information as well as company document layouts. Since the EvolutionCommon contains central and common information it is only necessary to have one EvolutionCommon database. Each Company/Client database is located together with the EvolutionCommon database and appears on the Evolution Login form as follows:

SDKLicense3.png

A evolution company database can be edited to see which EvolutionCommon is linked to it. Just like how Evolution run of two databases to use the SDK dll you need to supply connection information for both the Evolution database and EvolutionCommon database, either as a formatted connection string or as separate parameters: server name, database name, etc. The developer Serial Number and Authorisation key also needs to be provided as discussed under Licensing.

The Evolution SDK dll is master version dependable. The Master version is determined by the first three digits of the version number. This means that if you using any Evolution version beginning with 6.81… than any SDK Version that begins with 6.81… will be compatible if using any Evolution version beginning with 7.00… than any SDK Version that begins with 7.0.0… will be compatible.

The connection information can be supplied individually: 

using Pastel.Evolution;
DatabaseContext.CreateCommonDBConnection();
DatabaseContext.SetLicense("serial_number", "auth_key");
DatabaseContext.CreateConnection("your_sql_server", "your_db");
 ...or by using a single function call:
DatabaseContext.Initialise("your_db", "your_sql_server", "", "","", "your_auth_code");

Take note of the following: There was no class initialised; all the above methods are static. If you prefer calling the functions separately, they must be called in the same order as above. There are various overloaded versions of the above functions to suit a variety of server configurations. When connecting through COM, you will have to instantiate an instance of the ComHelper class and use it to initialise. The ComHelper class does not contain the overloaded methods and you will have to pass in formatted connection strings. //There are various overloaded methods for this 

DatabaseContext.Initialise("[DB]", "[Server]", "[Login]", "[Pwd]", "DEMO", "57571657837077");

Licensing

There are two License requirements that relate to the Evolution SDK.

  • Evolution SDK Developer License

The first is the SDK developer license which is purchased by a developer and allows the developer to use the SDK dll to develop any number of third party applications.

After purchasing the SDK Developer License a serial number(DE000000 in example) beginning with DE is issued on the Invoice. This serial number is given to our registrations department who will issue an authorisation code(123456789 in exampl). The Serial Number together with the Authorisation code is used to initialise a connection, please see the following example. To Register the SDK Developer Serial Number or SDK Connector Module contact the Sage Evolution Registrations department on +2711 304 3975 or email [email protected].

Create a call in your application code as follows: 

DatabaseContext.CreateCommonDBConnection("(local)", "EvolutionCommon", "user", "password", false);
DatabaseContext.SetLicense("DE000000", "123456789");
DatabaseContext.CreateConnection("(local)", "EvolutionCOMPANY", "user", "password", false);
// OR:
DatabaseContext.Initialise("EvolutionCOMPANY", "EvolutionCommon", "(local)", "user", "password", "DE000000", "123456789");

Together with the SDK developer License a 1 user Evolution License is provided as well which includes the SDK Connector module so that the developer can initialise a connection to the EvolutionCommon database(This forms part of the second license).

Therefore, whenever the application starts up, the SDK validates the auth code against the serial number supplied as well as whether the SDK connector Module is registered.

  • Evolution SDK Connector License

The second license is actually a module called the SDK Connector. This license is issued as a Sage Evolution add-on module and has to be activated just like any other module. Whoever purchases the application from the developer and wishes to use it in Evolution will also have to purchase the SDK connector module. This allows the user to make a connection between the third party application and Evolution.

Remember with the Evolution Developer License you receive a 1 user Evolution License which includes the SDK Connector module.

To Register the SDK Developer Serial number or SDK Connector Module contact the Sage Evolution Registrations department on +2711 304 3975 or email [email protected]. You will be guided through registering your EvolutionCommon database with the "SDK Connector Module". This is done in Evolution by either creating a new EvolutionCommon and following the registration wizard or by registering a existing EvolutionCommon by going to Utilities in the menu and then registrations which launches the Registrations wizard. The pin number generated by the wizard needs to be provided to the registrations team who will provide a registrations code in the format XXXXXX-XXXX-XXXXXX-XXXX-XXXXXX-XXXX-XXXXXX-XXXX.

SDKLicense1.png

The test for having the connector module registered is to log into Evolution and then going to Help | About. Look for "SDK Connector" in the Modules Registered list.

SDKLicense2.png

Renewal

  • Developer License - This license does not expire so your applications will run as long as the SDK Connector Module gets renewed, but no support will be offered, nor access to this site permitted, nor product updates be made available unless it gets renewed. The single-user Evolution license will also expire in the process, so no access to the Evolution product will be possible until renewed.
  • Connector License - This license(SDK Connector Module) has to be renewed annually, either stand-alone or as part of the developer license. Unless renewed, any SDK-related procedures will fail.
Retrieved from "https://developerzone.pastel.co.za/index.php?title=Evolution&oldid=273"