View source for Plug-in assemblies

{{Logic TOC}}
This document is a brief summary of '''plug-in assemblies''' in [[Resco Cloud]] and their implementation to the processes (workflows).

== Getting started ==

Plug-in assemblies allow you to run custom C# code on the Resco Cloud as part of the [[Admin_Console#Processes|Processes]]. Plugins can run periodically as jobs or be triggered as workflows. It should solve the limitations of the no-coding editor of processes. There are the typical use cases:

* complex logic of process
* communication with some third party system
* etc.

In [[Resco Cloud]], you can manage plugins using the [[Admin Console]].

== Creating a plug-in assembly ==

# Download [https://app.resco.net/docs/RescoCRM.Plugin.SDK.zip Resco SDK].<br>Sample projects are part of the RescoCRM.Plugin.SDK.zip file.
# Create a new project as a Class Library (.NET Framework 4.8 or later).
# Add a reference to the downloaded XRMServer.Core.dll.<br>[[File:Add reference to dll.png|alt=Creating a plug-in assembly: Add reference to dll|600px]]<br>[[File:Add reference to dll 2.png|alt=Creating a plug-in assembly: Add reference to dll 2|600px]]
# Implement the PluginBase interface.<br>[[File:PluginBase interface.png|alt=Creating a plug-in assembly: PluginBase interface|600px]]

=== Return value of plugin ===

You can define the return value of your plugin.

Implement the IPluginReturnValue interface to the code (e.g. string):

[[File:IPluginReturnValue.png|alt=Plug-in assemblies: Return value of plugin: IPluginReturnValue|600px]]

These are the allowed return types: It should be possible to create a variable of this type in Processes editor.

[[File:Allowed return type.png|alt=Plug-in assemblies: Return value of plugin: Allowed return type]]

=== Input values of plugin ===

You can define the input values of your plugin.

[[File:Input values.png|alt=Plug-in assemblies: Input values of plugin: Input values|600px]]

The name of the PluginInputParameter (MyPluginInput in the example), will be visible in the Processes editor.

[[File:MyPluginInput.png|alt=Plug-in assemblies: Input values of plugin: MyPluginInput]]

=== Logs ===

<syntaxhighlight lang="c#">
context.AppendLogLine("Contacts with specified account id '{0}' cannot be found!", accountId);
</syntaxhighlight>

Logs are saved and visible in the Admin Console under '''Processes Center > Logs'''.

=== Cancel the workflow execution ===

<syntaxhighlight lang="c#">
context.AppendLogLine("Contacts with specified account id '{0}' cannot be found!", accountId);
return PluginResult.Failed;
</syntaxhighlight>

=== Examples ===

Fetch

[[File:Example-fetch.png|alt=Plug-in assemblies: Cancel the workflow execution: Example fetch|600px]]

Create

[[File:Example-create.png|alt=Plug-in assemblies: Cancel the workflow execution: Example create|600px]]

Update

[[File:Example-update.png|alt=Plug-in assemblies: Cancel the workflow execution: Example update|600px]]

Delete

[[File:Example-delete.png|alt=Plug-in assemblies: Cancel the workflow execution: Example delete|600px]]

== Adding plug-in assembly to the Resco Cloud ==

In the development tool:
# Build the solution.<br>[[File:Build solution.png|alt=Adding plug-in assembly to the Resco Cloud: Build solution|600px]]
# Create the zip file with the dll file.<br>[[File:Create zip.png|alt=Adding plug-in assembly to the Resco Cloud: Create zip|600px]]

In the Admin Console:
# Go to '''Processes Center > Plug-in Assemblies'''.
# Click '''New''', then click '''Browse''' and upload the zip file.

The plugin is loaded and the return type and input parameters listed below (if implemented).

[[File:Plugin successfully loaded.png|alt=Adding plug-in assembly to the Resco Cloud: Plugin successfully loaded|600px]]

{{Note|If you don't see the plugin in the list, log out and then log back in.}}

== Executing plugins ==

# In the Admin Console, go to '''Processes Center > Processes'''.
# Click '''New''' to [[Server processes|create a new process]].
# As '''Category''', select Workflow or Job.
# If your plugin has a return value, it is necessary to add the variable of this type to the editor, then you are able to select the plugin.

[[File:Process using the demo plugin.png|alt=Plug-in assemblies: Executing plugins: Process using the demo plugin|600px]]

=== Process logs ===

Whenever a process is executed, the run generates a log file entry. To access the logs, go to '''Processes Center > Logs'''.

[[File:Process log.png|alt=Plug-in assemblies: Process log|600px]]

== Exporting plugins ==

If you need to transfer a plugin from one organization to another:
# In the [[Admin Console]], go to '''Settings > Organization'''
# Click '''Export Organization''' and select '''Custom'''.
# Select '''Plug-ins''' and click '''Export'''.

You can then import the files to the other organization using the '''Import Organization''' button.

Alternatively, you can export/import plugins between [[Admin_Console#Environments|connected environments]].

== Exception: There is already an open DataReader ==

When you fetch data but don't use the result, you can encounter the exception <code>System.InvalidOperationException: There is already an open DataReader associated with this Command which must be closed first</code>. To avoid this problem, make sure that all fetch results are used.

== Example: Schedule a workflow ==

One of the possible use cases is to schedule a job with a delay. For example, you have a trigger that executes when a new account record is created. You don't want to perform the follow-up action immediately but after a delay.

Use the following sample to schedule the job.

<syntaxhighlight lang="js">
protected void ScheduleJob()
{
    // schedule job
    var processService = this.Context.GetService(typeof(IPluginProcessService)) as IPluginProcessService;
    if (processService != null)
    {
        var job = new PluginScheduleJob();
        job.Name = $"Scheduled Test Job";
        job.RegardingObjectId = new XRMServer.Data.EntityReference(Guid.NewGuid(), "account");
        job.TriggerAt = DateTime.Now.AddMinutes(1);
        job.TypeName = typeof(Fieldiu.Plugins.accountP).FullName;
        job.Data = this.SerializeData(data);
        processService.ScheduleJob(job);
    }
}
</syntaxhighlight>

To send data for the job, use the following line:

<syntaxhighlight lang="js">
job.Data = this.SerializeData(data);
</syntaxhighlight>

In the scheduled job, this is how you can retrieve the data as the input parameter:

<syntaxhighlight lang="js">
object userData;
if (!this.Context.InputParameters.TryGetValue(PluginInputParameterName.UserData, out userData))
	return PluginResult.Canceled;
var mySerializedData = (string)userData;
</syntaxhighlight>

A similar solution can also be useful for long-running jobs. In that case, replace <code>TriggerAt</code> with <code>job.Recurrence = processService.GetRecurrence(0, 1);</code>. Keep in mind that long-running jobs (e.g., when generating some statistics) must be stopped after 5 minutes (or they will be aborted by the system). Return <code>PluginResult.InProgress</code>. Store the current state into data: <code>this.Context.InputParameters[PluginInputParameterName.UserData] = this.SerializeBatchData(result, entity);</code>. When everything is complete, return <code>PluginResult.Succeeded;</code>













{{Feedback}}
[[Category:Resco Cloud]]
[[Category:Business logic]]