create setup form for custom module

Question

I have a custom module getting executed right after the PDFGenerator finished. I followed this guide on how to create a custom module

https://stackoverflow.com/a/55799101/9945420

When processing a batch document I want to manipulate the generated PDF file and add a footer to that file. The content of that footer needs to get configured in the Administration module.

So within my project called "StampOnScanProcess" I added a Folder called "Setup" with two files. A Form called "FrmSetup"

public partial class FrmSetup : Form
{
    private IBatchClass batchClass;

    public FrmSetup()
    {
        InitializeComponent();
    }

    public DialogResult ShowDialog(IBatchClass batchClass)
    {
        this.batchClass = batchClass;

        // Load previous Settings ...

        return this.ShowDialog();
    }

    private void btnCancel_Click(object sender, EventArgs e)
    {
        this.Close();
    }

    private void btnSave_Click(object sender, EventArgs e)
    {
        // Save ...

        this.Close();
    }
}

and a UserControl called "UserCtrlSetup"

[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
public interface ISetupForm
{
    [DispId(1)]
    AdminApplication Application { set; }

    [DispId(2)]
    void ActionEvent(int EventNumber, object Argument, out int Cancel);
}

[ClassInterface(ClassInterfaceType.None)]
[ProgId(CUSTOM_MODULE_NAME_SETUP)]
public partial class UserCtrlSetup : UserControl, ISetupForm
{
    private const string CUSTOM_MODULE_NAME_SETUP = "StampOnScanProcess.Setup";

    private AdminApplication adminApplication;

    public AdminApplication Application
    {
        set
        {
            value.AddMenu(CUSTOM_MODULE_NAME_SETUP, CUSTOM_MODULE_NAME_SETUP, "BatchClass");
            adminApplication = value;
        }
    }

    public void ActionEvent(int EventNumber, object Argument, out int Cancel)
    {
        Cancel = 0;

        if ((KfxOcxEvent)EventNumber == KfxOcxEvent.KfxOcxEventMenuClicked && (string)Argument == CUSTOM_MODULE_NAME_SETUP)
        {
            FrmSetup form = new FrmSetup();
            form.ShowDialog(adminApplication.ActiveBatchClass);
        }
    }
}

I modified my registration file and added the setup form to it

[Modules]
StampOnScanProcess

[StampOnScanProcess]
RuntimeProgram=StampOnScanProcess.exe
ModuleID=StampOnScanProcess.exe
Description=...
Version=10.2
SupportsNonImageFiles=True
SupportsTableFields=True
SetupProgram=StampOnScanProcess.Setup

[Setup Programs]
StampOnScanProcess.Setup

[StampOnScanProcess.Setup]
Visible=0
OCXFile=StampOnScanProcess.exe
ProgID=StampOnScanProcess.Setup

When launching the Administration module I head over to the Batch Class Properties => Queues and want to call this setup form by clicking the Properties button in the middle.

Unfortunately the properties button is disabled so I can't open the setup form. This form gets added to the context menu of the batch class

How can I bind this form to the properties button instead? And what is the best way to store configured data and access it when the runtime application gets executed?

I need to think about how to store data because some users have user profiles

and the runtime application currently logs in with no credentials.

    public void LoginToRuntimeSession()
    {
        login = new Login();
        login.EnableSecurityBoost = true;
        login.Login();
        login.ApplicationName = CUSTOM_MODULE_ID;
        login.Version = "1.0";
        login.ValidateUser($"{CUSTOM_MODULE_ID}.exe", false, "", "");
        session = login.RuntimeSession;
    }

So it might happen that I have to store the credentials on setup too.

Answer 1

How can I bind this form to the properties button instead?

All interactions with menu entries are handled by ISetupForm.ActionEvent. New entries are added with the AddMenu method of the AdminApplication object. Kofax differentiates between multiple entries by name - imagine that you could have multiple menu entries at the same time, one on batch class level, another one on document class level, and another one in the ribbon - just to name a few examples. Kofax uses the same approach in any component that integrates into Administration (e.g. Custom Modules or Workflow Agents).

This is an example from one of our components. Note that three entries are added on BatchClass level and two more on DocumentClass level.

value.AddMenu("BatchClass.GeneralConfig", "Field Panel - General Configuration", "BatchClass");
value.AddMenu("BatchClass.FieldEditor", "Field Panel - Configure Batch Fields", "BatchClass");
value.AddMenu("DocumentClass.FieldEditor", "Field Panel - Configure Index Fields", "DocumentClass");
value.AddMenu("CopyBatchFieldConfig", "Field Panel - Copy Batch Field Configuration", "BatchClass");
value.AddMenu("PasteBatchFieldConfig", "Field Panel - Paste Batch Field Configuration", "BatchClass");
value.AddMenu("CopyIndexFieldConfig", "Field Panel - Copy Index Field Configuration", "DocumentClass");
value.AddMenu("PasteIndexFieldConfig", "Field Panel - Paste Index Field Configuration", "DocumentClass");

Each entry is no identified by its event text, the first parameter. For example, BatchClass.GeneralConfig is intended to open up a generic configuration dialog - on batch class level.

Now, back to our ActionEvent - this is how I distinguish between the entry selected by the user:

if ((KfxOcxEvent)EventNumber == KfxOcxEvent.KfxOcxEventMenuClicked)
{
    AdminForm form = new AdminForm();
    switch ((string)Argument)
    {
        case "BatchClass.GeneralConfig":
            ConfigureGeneral(kcApp.ActiveBatchClass);
            break;

[I] want to call this setup form by clicking the Properties button in the middle.

I don't know if you can use this button - I would assume yes - yet personally I tend to put settings either on batch or document class level. For example - your PDF annotation settings may different from document class to class - having an entry on this level seems more natural.

And what is the best way to store configured data and access it when the runtime application gets executed?

Custom Storage Strings, and you can let your imagination run wild here. The most simplistic approach is to store key-value pairs during setup, and retrieve them in runtime. Here's a generic call (BatchClass is an IBatchClass object, i.e. a pointer to the ActiveBatchClass property of the AdminApplication object):

// set a CSS
BatchClass.set_CustomStorageString(name, value);
// get a CSS
BatchClass.get_CustomStorageString(name)

I usually use a single custom storage string only and store custom object - the object is a base64-encoded serialized XML using XmlSerializer - but again, that's up to you. The only recommendation is to rely on CSS only - don't use external files to store configuration parameters. A CSS is an integral part of your batch class - so, when exporting said class and importing it on a different system, your entire configuration will be there.

I need to think about how to store data because some users have user profiles

Usually, you don't need to worry about that. The properties for user and password in ValidateUser are entirely optional - and since you're planning to write an unattended module - ideally a Windows Service, credentials should be maintained there. Kofax and Windows would automatically make sure the credentials are passed on, and your module will run under this user's context. Just make sure the user has permissions for the module and all associated batch classes. It's different if you're planning to write an attended module, for example an enhanced Validation module.