Implementing Custom Code

EngageIP provides support for adding code blocks or full C# classes in order to add custom business logic to a deployment. Full C# solutions are called Custom Code. Code blocks are referred to as Scripts and are used in other parts of the system.

For Custom Code all classes need to be contained within a single file when they are uploaded in the EngageIP AdminPortal Setup Custom Code screen. It is not possible to have references outside of a single custom code file except for EngageIP assemblies. For example, one custom code file cannot reference another custom code file.

There are no naming restrictions except that namespaces must be unique between all EngageIP assemblies and all loaded custom code files. The directory structure conventions are located here: Custom Code Folder Structure and Naming Conventions.

All Custom Code files can implement the optional C# ICustomCodeInstaller interface to perform one time business logic when the custom code is loaded into EngageIP. This interface defines a single method: Install(int ownerID). EngageIP will compile the entire file and execute the Install method when the custom code file is uploaded via the AdminPortal UI. This Install method is where any setup or registration logic should be performed. Some examples are:

add profile questions
schedule jobs
modify database schema

One Custom Code file may contain implementations of several C# interfaces other than ICustomCodeInstaller. No other classes or methods will be invoked during upload time as they will be triggered or executed by other mechanisms in EngageIP.

Event Codes

The preferred way of creating custom code to integrate with real time events is by having the custom code class implement the EngageIP C# IAction interface. Registering event codes is achieved by implementing the EventCode property Get method and returning a string with a comma separated list of event codes applicable to this custom code file. For example, "User.Create, Payment.Create" or "Package.Update". All business logic that needs to be executed will chain from the Run(ScriptContext context) method of IAction. The ScriptContext contains two key pieces of information:

The ID of the object that has changed
A serialized copy of the object before the change was made

These two pieces of information will be used to allow the custom code to efficiently know what instance of the object triggered the event code.

Interfaces

The following interfaces are available to be used:

ICustomCodeInstaller - Used to configure EngageIP to have necessary configuration performed to support custom code. This is run every time custom code is compiled.
IAction - Represents a workflow of one step, called when a specified Create, Update or Delete event happens on a supported entity.

public interface ICustomCodeInstaller {
	void Install(int ownerID);
}
public interface IAction {
   string Name { get; }
   string Description { get; }
   string EventCode { get; }
   /// <summary>
   /// This is used by the script engine to keep track of the OwnerID for this action
   /// </summary>
   int OwnerID { get; set; }

   void Run(ScriptContext context);
}