Customization File

You can customize your Process Director installation by editing the customization file, vars.cs.ascx, that's located in the \Program Files\BP Logix\Process Director\website\custom\ directory of your Process Director installation. This directory is created during the initial installation of the product. The files in this directory are not overwritten during subsequent installations, such as when you perform an upgrade to a new version of Process Director.

The customization file is separated into several methods, each of which enables you to customize some aspect of Process Director. Please expand the code example below to see an example of the customization file and its organization.

Code Example

The following are called only for the vars files:

// Called BEFORE database initialized
public override void PreSetSystemVars(BPLogix.WorkflowDirector.SDK.bp bp)
{
}

// Called AFTER database initialized
public override void SetSystemVars(BPLogix.WorkflowDirector.SDK.bp bp)
{
    // Before making SDK calls that access the database, ensure DB has
    // been opened by checking bp.DBOpenComplete
}

// Called on pages that are "in" a partition
public override void SetPartitionVars(BPLogix.WorkflowDirector.SDK.bp bp,
                                      BPLogix.WorkflowDirector.SDK.Partition Partition)
{
}

/*
// This override allows you to return different values based on a token
// The default operator simply stores the values in a Dictionary
// Example: bp.Vars["GlobalVar1"] = "My Value";
public override string this[string pToken]
{
    get
    {
        return "Token value: " + pToken;
    }
    set
    {
    }
}
*/

// Called on every login for customizing the error checking of a user
public override bool CanLogin(BPLogix.WorkflowDirector.SDK.bp bp,
                              Login_Struct pLoginStruct,
                              out string pErrorString)
{
    pErrorString = null;

    /*
    if (pLoginStruct.UserID.ToUpper() == "BAD_USER")
    {
        pErrorString = "That is a bad user";
        return false; // Prevent login
    }
    */
    return true; // Allow login
}

// Called to test if user can call specific web service
public override bool CanCallService(BPLogix.WorkflowDirector.SDK.bp bp,
                                   User CurrentUser, string API)
{
    return true;
}

// Called to test if we can disable this user
public override bool CanDisableUser(BPLogix.WorkflowDirector.SDK.bp bp,
                                    string UID,
                                    out string Reason)
{
    Reason = null;
    return true;
}

// Called after every successful login
public override void LoginComplete(BPLogix.WorkflowDirector.SDK.bp bp,
                                   Login_Struct LoginStruct,
                                   User CurrentUser)
{
}

// Called after every logoff
public override void LogoffComplete(BPLogix.WorkflowDirector.SDK.bp bp,
                                    User LogoffUser)
{
}

// Called to return the optional page to navigate to after the login occurs
public override string GetFirstPage(BPLogix.WorkflowDirector.SDK.bp bp,
                                    string pFirstPage)
{
    return base.GetFirstPage(bp, pFirstPage);
}

// Called when a user clicks on "forgot password". In this callback, you can set a
// new password for the user,
// and you can force the user to change their password after their first login.
// Return true to allow the password retrieval, or false to prevent the password retrieval.
// Note that fAllowRetrievePassword must be set to true to allow any user to
// retrieve their password. Only built-in (vs Active Directory) users
// can retrieve their password.
public override bool ForgotPassword(BPLogix.WorkflowDirector.SDK.bp bp,
                                    string UserID,
                                    string OldPassword,
                                    out string NewPassword,
                                    out bool MustChangePassword)
{
    NewPassword = null; // Do not change old password
    MustChangePassword = false; // Do not force user to change password after login
    return true;
}

// Called to validate a password change for a user
// Return true to allow the password change, or false to prevent
// the change. You can set the Reason parameter
// to a string representing the reason for the invalid password
// (e.g.,, password too short)
// NOTE: This is only enabled with the "Compliance Option"
public override bool ValidatePassword(BPLogix.WorkflowDirector.SDK.bp bp,
                                      string UserID,
                                      string OldPassword,
                                      string NewPassword,
                                      out string Reason)
{
    Reason = null;
    /*
    // Example to ensure all new passwords are at least 5 characters long
    if (NewPassword.Length < 5)
    {
        Reason = "password too small";
        return false;
    }
    */
    return true;
}

// Called to customize the string that is displayed for each user.
// This will set the display string for the entire product.
// NOTE: You must set fAllowCustomUserString to true in order for this exit to be called
public override void UserDisplayString(BPLogix.WorkflowDirector.SDK.bp bp,
                                       ref string UserString,
                                       User UserClass)
{
    /*
    // This will add the custom string to the end of the user display string
    if (!UserClass.CustomString.bpIsNullOrEmpty())
    {
        UserString = UserString + " / " + UserClass.CustomString;
    }
    */
}

// Called to customize the string that is displayed for each user.
//This will set the display string only in the object that calls this function.
// NOTE: You must set fAllowCustomUserString to true in order for this exit to be called
public override void UserDisplayString2(BPLogix.WorkflowDirector.SDK.bp bp,
                                       ref string UserString,
                                       User UserClass)
{
}

// This event is called prior to synchronizing a user from Active Directory
// using the AD Sync Profiles.
// Returning true allows the user to be sync'ed. Returning false will
// prevent the user from being sync'ed.
public override bool AD_Sync_User(BPLogix.WorkflowDirector.SDK.bp bp,
                        string ProfileName,
                        System.DirectoryServices.AccountManagement.UserPrincipal User)
{
    /*
    // Do not sync the user if the email address is null
    if (string.IsNullOrEmpty(User.EmailAddress))
        return false;
    */
    return true;
}

// This event is called after synchronizing a user from Active Directory using the AD Sync Profiles.
// This can be used, for example, to modify the user record after the sync.
public override void AD_Sync_User_Complete(BPLogix.WorkflowDirector.SDK.bp bp,
                           string ProfileName)
                           System.DirectoryServices.AccountManagement.UserPrincipal User,
                           string UID)
{
    /*
    var TempUser = BPLogix.WorkflowDirector.SDK.User.GetUserByID(bp, UID);
    if (TempUser != null)
    {
        TempUser.CustomString = "Some custom value";
        TempUser.UpdateUser();
    }
    */
}

// This event is called prior to synchronizing a group from Active Directory
// using the AD Sync Profiles.
// Returning true allows the group to be sync'ed.
// Returning false will prevent the group from being sync'ed.
public override bool AD_Sync_Group(BPLogix.WorkflowDirector.SDK.bp bp,
                         string ProfileName,
                         System.DirectoryServices.AccountManagement.GroupPrincipal Group)
{
    return true;
}

// This event is called after synchronizing a group from Active Directory using the AD Sync Profiles.
public override void AD_Sync_Group_Complete(BPLogix.WorkflowDirector.SDK.bp bp,
                   string ProfileName,
                   System.DirectoryServices.AccountManagement.GroupPrincipal Group,
                   string GID)
{
    /*
    var TempGroup = BPLogix.WorkflowDirector.SDK.Group.GetGroupByID(bp, GID);
    if (TempGroup != null)
    {
    }
    */
}

// Called when a sync profile starts / end
public override void AD_Sync_Start(BPLogix.WorkflowDirector.SDK.bp bp,
                                   string ProfileName,
                                   string ProfileID,
                                   bool TestMode)
{
}

public override void AD_Sync_End(BPLogix.WorkflowDirector.SDK.bp bp,
                                 string ProfileName,
                                 string ProfileID,
                                 bool TestMode)
{
}

While many different aspects of your installation's operation can be altered via writing your own C# code in the customization file, the primary customization method is to use one or more of the many Custom Variables that are already built into the product, and which provide an easy means of changing the default operation of the system. The built-in Custom Variables are organized into different categories in this documentation, as outlined in the Custom Variables topic.

Note Access to the customization file is generally limited to On-Premise customers. Customers with Cloud installations can only access their customization file directly via an additional license option that enables them to access the /custom folder via an SFTP connection. Otherwise, Cloud customers can submit a technical support ticket that describes the desired change, and BP Logix will make it for them.

Form Control Styles

Forms have the ability to set the style for Enabled/Disabled form controls, Required form fields, and form fields in an error state using the “Default Styles” section on the Form properties page. To modify the list of default styles displayed in the dropdown, edit the vars.cs.aspx file.

Creating Your Own Custom Variables

Process Director enables you to set your own system variables in the vars.cs.ascx file. All custom vars that you create are formatted as strings, so you should use string syntax when setting the variable's value, i.e., use double quotes ("") around the value. Process Director will convert custom vars to numbers on the fly if numeric comparisons or calculations are required. Custom vars that you create are stored in a custom dictionary as key/value pairs.

There are two methods available in the custom vars file for creating custom vars: SetSystemVars and PreSetSystemVars. The PreSetSystemVars method is called prior to initializing the Process Director database, while the SetSystemVars method is called after database initialization.

In general, this means that the default method to use when creating custom vars is the PreSetSystemVars method; however, if you need to set the value of the var based on information stored in the Process Director database, such as the identity of the user or the workspace in which the user is working, you must use the SetSystemVars method.

Using the syntax {CustomVar:MY_VAR} elsewhere in Process Director will return the custom variable (in this case, MY_VAR) value that was defined in the customization file.

Session Variables

Process Director provides the ability to create session variables. These variables exist only for the length of a single user session, and are discarded when the user's session ends, such as when the user logs out of Process Director, or after the specified period of inactivity that is set in IIS. Session variables can be created via custom scripting in a Form or process, or inside one of the sections of the customization file, depending on when it's necessary to create the variable. For instance, if you want to set the session variable any time a page loads in a partition, you could set the session variable in the SetPartitionVars method of the customization file.

Once the session variable has been set, the variable is addressable through code, or in any Process Director Object using the Session System Variable .

Shared Delegation

Shared Delegation can be universally disabled in the Custom Vars file via the SharedDelegationAllowed method.

Documentation Feedback and Questions

If you notice some way that this document can be improved, we're happy to hear your suggestions. Similarly, if you can't find an answer you're looking for, ask it via feedback. Simply click on the button below to provide us with your feedback or ask a question. Please remember, though, that not every issue can be addressed through documentation. So, if you have a specific technical issue with Process Director, please open a support ticket.

Send Feedback to BP Logix