SDK: Building a Module (Advanced)
  • 28 Jan 2022
  • 5 Minutes to read
  • Dark
    Light

SDK: Building a Module (Advanced)

  • Dark
    Light

Version 7.x .NET Architecture Change

Overview

Decisions supports two types of modules: core and custom

Core modules are built, shipped, and are a part of the base product. 

Custom modules are created by users to add or extend certain functionalities and to link together different types of custom functionality. While custom modules do not require .dlls, it is a common practice to build custom code in a .dll.

A use of custom module may involve grouping exported Decisions Objects, custom Flow behaviors, and/or step implementations together in one module, integrating custom Flow or step implementations with a third party library, etc.

If needing to update a custom module, refer to the Updating Custom Modules article.



Creating a Custom Module

Want to follow along with an example custom module?
The .net project referenced throughout this document is located on GitHub. Download this to follow along with the examples.

Developers may create custom modules in one of two ways:

  •  Running a Create Module executable that installs with the product
  •  Building the module folder structure and Module XML descriptor file manually.

Generating Module Folder Structures using CreateModule.exe

The CreateModule.exe is a command-line executable that generates the module structure and manifest. Using the CreateModule.exe automatically names all the folders and directories correctly. It may also create client DLLs if necessary that allow other projects to CALL services in the module.

  1. Open an elevated command prompt such as Windows cmd or PowerShell window and navigate to C:\Program Files\Decisions\Decisions Server.
  2. Use the following command to build a module and point it to the DLL that contains all of the items for the module:
    .\CreateModule.exe -buildmodule CustomModule -output C:\ -frontendclientsdir 'C:\Program Files\Decisions\Decisions Server\framework' -coreclientsdir 'C:\Program Files\Decisions\Decisions Server\framework' -services 'C:\workspaces\sdk-examples\CustomModule\bin\Debug\CustomModule.dll'
    The following files and folders should generate upon running the command.
    SDK-DevCustomMod (1).png

  3. Also enter the following command builds a module and points it to the DLL containing all items for the module as well as the third party DLL that it relies on it named 'MathNet Numerics'.
    .\CreateModule.exe -buildmodule CustomModule -output C:\ -frontendclientsdir 'C:\Program Files\Decisions\Decisions Server\framework' -coreclientsdir 'C:\Program Files\Decisions\Decisions Server\framework' -services C:\workspaces\sdk-examples\CustomModule\bin\Debug\CustomModule.dll C:\workspaces\sdk-examples\CustomModule\bin\Debug\MathNet.Numerics.dl
    The following .dll files should show once running the command.

The following code example demonstrates other usage and options with the command line 

Modules Builder Command-Line Tool 
Usage: 
CreateModule.exe -buildmodule  -output  -frontendclientsdir 'C:\Program Files\Decisions\Decisions Server\framework' -coreclientsdir 'C:\Program Files\Decisions\Decisions Server\framework'

CreateModule.exe -buildnetclients  -output  -frontendclientsdir 'C:\Program Files\Decisions\Decisions Server\framework' -coreclientsdir 'C:\Program Files\Decisions\Decisions Server\framework'

 CreateModule.exe -buildclients  -output  -frontendclientsdir 'C:\Program Files\Decisions\Decisions Server\framework' -coreclientsdir 'C:\Program Files\Decisions\Decisions Server\framework'

CreateModule.exe -buildruntimeassemblyclients   -output  -frontendclientsdir 'C:\Program Files\Decisions\Decisions Server\framework' -coreclientsdir 'C:\Program Files\Decisions\Decisions Server\framework'
    : [, , ..., ]   Sources:           -services       :   includes services dlls           -clilibs        :   includes cli dlls           -sllibs         :   includes silverlight dlls           -compslibs      :   includes components dlls           -weblibs        :   includes web dlls           -webpages       :   includes web pages files           -agentlibs      :   includes agent dlls           -scripts        :   includes scripts           -mssql  :   includes sql scripts           -mysql  :   includes sql scripts           -azure  :   includes sql scripts           -objects        :   includes objects to import
   Modules Dependencies:          -refmodules  ...    More Options:          -failifwarning : fail is there's any warning


Manually Building the Module Folder Structure

The Module Folder structure only contains the folders necessary for building the module and an XML file describing the zipped module so Decisions will recognize it. 

  1. Build a dll file from code project.
  2. Create a folder with the desired name for the module.
  3. Create a CoreServicesDlls directory inside the module folder.
  4. Paste the custom DLL into the CoreServicesDlls directory.
  5. Create a module.xml file inside the module folder.
  6. Zip the module folder. 
  7. Paste the ZIP file to C:\Program Files\Decisions\Decisions Server\CustomModules.

After the module installs, the following empty directories will be created located at C:\Program Files\Decisions\Decisions Server\modules\[Module Name].

Custom Module FolderUse RelevanceDescription
AgentDLLsNot typically usedExtra DLL files for adding the capability to the Decisions Cloud to Site Agent.

If not using the agent and extensions to the product do not need to be run through the agent, this folder can be safely ignored.
CoreServicesDllsMost commonly usedThis folder contains a DLL or multiple DLLs that define a project's Flow steps, Rule parts, customizations, behaviors, initializer code for setup, and more.

If these files have any Web Services that are registered in this folder, then the user will get corresponding ServiceClient DLLs in the ServiceClientDlls folder. These are created by the CreateModule.exe tool.
ImportedObjectsCommonly usedFlows, Pages, Reports, Rules, and Folders that have been built in the Decisions designers and exported from Decisions using the Import/Export function. These should be .decObj files.
JSClientsNot typically usedIf the CoreServicesDlls folder contains DLL files that declare new Web Services (IServiceContract) that also have [AutoRegister] attributes then JSClients will be created when running the CreateModule.exe file while building module.
MvcDllsNot typically usedFolder for compiled Dlls of MVC views and controllers
MvcStylesNot typically usedFolder for stylesheets for the module
MvcViewsNot typically usedThese are additional MVC Views that are hosted in the Decisions.Web. The host is the primary user interface. MvcViews can be used to add additional view controls for pages and forms.

These files go to the Web Host/HUI virtual directory in the installation. HUI is the virtual directory that serves the HTML portal to users.
ServiceClientDllsMost commonly usedSee note on CoreServicesDlls. This folder does not usually contain any custom assemblies, only those generated during module build.
SQLNot typically usedThis has different sections for SQLScript / MySQLScript / OracleScript / AzureScript. These are database scripts that will run when the module is deployed.

These are often used to add tables or stored procedures that this module relies on.
WebHostFilesNot typically usedWebHostFiles are DLLs that need to put in the Bin Folder of the Web Application. These are usually files that are in support of the WebPages listed below.
WebPagesNot typically usedHTML or ASPX pages that go in the root directory of the Web Host itself.

This folder must contain zip files that are unpacked on module installation. The unpacked files become peers to the Login.aspx page. This folder may contain folders and those folders will be maintained.
Module.xmlRequired for all custom modulesA manifest created manually or by the module build tool. It contains some basic info about where the module was built, at what time, for which version, and whether it depends on any other modules.

The Module Manifest File

The Module.xml file should have the following properties:

Property NameRequired?Function
DependsOnYesLists any other modules that this module depends on to function properly if any.
VersionNoProvides what Decisions version the module was developed for.
RequiresLicenseYesChecks if an external requires a license. For custom modules, this is always False.
CompiledOnDateYesThe timestamp the module was created.
CompileOnServerYesThe name of the computer the module was compiled on.

The following is an example of a Module.xml file:

<?xml version="1.0"?>
<ModuleInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<DependsOn />
<Version>5.16.0</Version>
<RequiresLicense>false</RequiresLicense>
<CompiledOnDate>2020-08-04T14:04:08.0177446-05:00</CompiledOnDate>
<CompiledOnServer>DESKTOP-XUT084L</CompiledOnServer>
</ModuleInfo>



Installing the Custom Module

Installing the custom module adds the CustomModules folder to the database so that the module can be restored on cluster nodes in a clustered environment. 
It will also install the module to the C:\Program Files\Decisions\Decisions Services Manager\modules directory and allows its respective steps, Rules, etc in Step Toolbox.

  1. Copy the Module ZIP file into C:\Program Files\Decisions\Decisions Server\CustomModules.
  2. Log in to Decisions Studio and navigate to My Apps > APP STORE > Modules.
  3. Find the custom module, click DETAILS and click INSTALL.



Best Practices

When creating a custom module, be sure to keep the following best practices in mind:

  • Create a module for service DLLs and a different module for all configurations to assist with breaking cycles apart if using a development team and design team.
  • Always version modules.
  • If issues arise, please refer to the various logs at C:\Program Files\Decisions\Decisions Services Manager\Logs.

Was this article helpful?