---

Plugin Version: 2.6.6 | Release Notes

---

Overview

The Enhanced Login plugin provides a higher level of security by creating and managing security policies inside ProcessMaker according to the settings made by an administrator user. The plugin monitors login sessions through the IP address where the session was started or through the IP address of the device (or both). It can block duplicate login sessions from the same user or login sessions from multiple devices.

It also adds a security layer to user login through a 2-step verification method. Users who are configured to have 2-step verification will receive an email with a verification token or a token matrix generated by the plugin. After logging into ProcessMaker with their user credentials (step 1), they must enter the code (step 2) to enter ProcessMaker.

In addition, the plugin also provides an easy-to-use interface to add password policies, which are normally set inside one of ProcessMaker's configuration files.

Requirements

• ProcessMaker Enterprise version 3.0 or higher with the corresponding license.
• Read this documentation to view the table of ProcessMaker's supported stacks.
• To view a list of supported browsers, read the following documentation.

Restriction

Please take into consideration the following restriction:

• SAML plugin cannot authenticate to the Enhanced Login plugin. Enhanced Login plugin does not authenticate users as does LDAP or the Google Authentication plugin.

Installation

Log in with a user, such as "admin", who has the PM_SETUP_ADVANCE permission in his/her role and then go to Admin > Plugins > Enterprise Manager. Either install the Enhanced Login plugin by clicking on Install from File and uploading the plugin file or by clicking on its Install Now button in the list of available plugins.

After installing the plugin, make sure that the Enhanced Login plugin is  enabled.

Configuring the php.ini

This plugin requires the following configuration in php.ini:

session.save_handler => files session.save_path => "Some_valid_path" //According to the version of php

session.save_path is a path that defines the argument which is passed to the save handler. If you choose the default files handler, this is the path where the files are created. This configuration is required for all version 3.x from ProcessMaker.

If your ProcessMaker instance is with PHP 7.1.x, use:

session.save_path = /var/lib/php/7.1/session

For more information see this documentation.

Glossary

• Coordinate Matrix: Matrix of printed serial numbers (usually paired data) ordered in rows and columns. Rows are titled with ascending numbers starting from 1 and columns are ordered alphabetically starting from A.
• Token: 5-digit code that is sent to the user in an email to allow authentication under the security policies set for the user login.
• PP: Passwords Policies.

Configuring the Plugin

To configure the plugin, go to the Admin section of ProcessMaker. Then, look for the Enhanced Login tab using the arrow at the right, and click on it to access its options.

The Enhanced Login tab has three available options to work with:

• 2 Step Verification
• Session Control
• Password Policy

2 Step Verification

This option is a login method that adds an extra layer of security, making it 2 steps to log in to ProcessMaker.

The first step is the normal login where users enter their username, their password and, optionally, the workspace they are working on. The second step asks users to enter a verification code generated by the plugin and sent to the user's email to allow access to ProcessMaker.

To configure this option, log in to ProcessMaker as a user who has the PROCESSMAKER_ADMIN role, such as "admin". Then, go to the Enhanced Login tab inside Admin panel. Click on the 2 step verification option in the left panel to access the list of users in the right panel.

There are two tabs available in this section:

• Users
• Token Providers Setup

Users

The Users tab shows a list of all the existing users and provides a dropdown to select their login method in the Verification Type column.

1. Regenerate Matrix: Generates a new token matrix and emails it to users whose login method is TWOSTEP_VERIFICATION_MATRIX. Remember that this button is available only if the user has the TWOSTEP_VERIFICATION_MATRIX method assigned.

   Select one user from the list and click the Regenerate Matrix button. A message like the one below will open:

   

   Click on Cancel to close the message, or click on OK to generate a new matrix and send it to the user's email. A new message will open:

   

2. Kill Session: Closes any active session. Select a user that has been set with a TWOSTEP_VERIFICATION_MATRIX or TWOSTEP_VERIFICATION_EMAIL verification type and click on the Kill Session button. A message like the one below will open:

   

   Click on Cancel to close the message, or click on OK to close the session. A new message will appear:

   

3. Search: Enter the user name, first or last name of a user into this field and click on the Search button to search for a particular user.
4. Verification Type: The verification type of a user, which can be none, TWOSTEP_VERIFICATION_MATRIX or TWOSTEP_VERIFICATION_EMAIL. For more information, read this section.

The list of users can be sorted based on either username, full name or status. To do this, hover the mouse pointer over the left side the column until a black down arrow appears, click on it to expand a menu. The columns can be sorted alphabetically in ascending or descending order.

Verification Type

The verification type of a user can be:

• TWOSTEP_VERIFICATION_MATRIX
• TWOSTEP_VERIFICATION_EMAIL

TWOSTEP_VERIFICATION_MATRIX

This option is only available in the Verification Type dropdown after configuring and enabling the Matrix option under Token Provider Setup.

By selecting this option, the user will receive an email with a matrix token generated by the system, which must be entered to access ProcessMaker. Read this section to learn how to enable and configure this option.

TWOSTEP_VERIFICATION_EMAIL

The TWOSTEP_VERIFICATION_EMAIL option is only available after configuring and enabling the Email option under Token Provider Setup.

By selecting this option, the user will receive an email with a code generated by the system, which must be entered to access ProcessMaker. To learn how to enable and configure this option, read this section.

Token Provider Setup

Click on this tab to configure the two methods to provide access tokens to users. These methods are Matrix and Email, which are explained below.

Matrix

The MATRIX option sends an email to the user with a token matrix generated by the plugin, which will allow the user to enter ProcessMaker. The system will ask for a specific coordinate of the matrix in the format letterNumber. For example, in a 100-cell matrix, there will be 10 rows and 10 columns (matrix are always square). Each row will be numbered starting from 1, and each column will be assigned a letter starting from A. Thus, the first cell will always be A1, the second cell in the first row will be B1 and so on.

To enable this option, configure the options detailed below:

• Enable/Disable: Enables or disables the method. If it is enabled, it will be available in the Verification Type column in the list of users, and it will be possible to make users log in with this method.
• Matrix size: Specifies the size of the square matrix used to generate the tokens.
• Token size: Specifies the number of digits or characters the token will have.
• Token type: Selects the type of token that will be built, which can be Numeric, Alphabetic and Alphanumeric.
• Generate matrix: Regenerates the matrix every "N" days and sends the new matrix to the user's email to log in again.
• Usage Time: Enables or disables the generation of a new matrix.

After the configuration is defined, click Save Settings to save the configuration. Click Save Settings even if this is the first time that the Matrix is being configured because this saves the default values of the Token type. After save settings, a confirmation message will be displayed:

After the user logs into ProcessMaker with their username and password, a new interface will open asking for the code, as in the following image:

The user must check his or her email inbox and open the email with the matrix of tokens generated. In this case, the size of the matrix is 4 and has alphanumeric tokens. In this example, the message in the window asks for C3, the code that must be entered into the field is in column C, row 3 (CR61).

Enter the code and click on the Submit button to access ProcessMaker.

Email

Enable this option to send a single login token to the user's email. The characteristics of the Email section are:

Where:

• Enable/Disable: Enables or disables the method. If it is enabled, this authentication method will be available in the Verification Type column in the list of users, and it will be possible to make users log in with this method.
• PP Token Length: Number of digits or characters the generated token will have.
• PP Email Type: The type of token generated: Numeric, Alphabetic or Alphanumeric.

Click on the Save Settings button to save all settings made in this section.

After the user logs into ProcessMaker with their username and password, a window opens asking for the code, as in the following image:

The user must check his or her inbox and find the email with the code generated. In this example, the code is DJFPY.

Enter the code (DJFPY) sent in the email and click on the Submit button to enter ProcessMaker.

Session Control

This option allows administrators to restrict open sessions belonging to one user. There are two ways to restrict user login:

• Restriction by IP: Restricts logins made by the same user from different IPs.
• Device restriction: Restricts logins made by the same user from different devices.

Both restrictions can be disabled, additional logins using the same credentials can be blocked when there already is an open session, or existing sessions can be killed to allow a new login.

To use this option, go to the Enhanced Login tab inside Admin, then click on the Session Control option in the left panel. A window with the following settings will open:

Where:

• IP Restriction: There are three settings for this option:
  • Disable: Select this option to disable this restriction and allow a user to login in the same IP address for multiple sessions.

  • Block Duplicate Session: Select this option to block any additional sessions belonging to the same user with the same IP address. The following message will be shown if a user tries to log in with the credentials of a user that has already a session open:

    

  • Kill Existing Session: Select this option to kill an existing session. This is very helpful, for example, if a user is trying to log in on another browser or on the same browser, but the session information has not been deleted. When this option is selected, the user will be able to enter ProcessMaker normally with the same IP address, but with a new session.
• Device Restriction: There are three settings for this option:
  • Disable: Select this option to disable this restriction and allow users to log in from different devices.

  • Block Duplicate Session: Select this option to block any attempt to start another session by the same user on another device. The following message will be shown if a user tries to log in with the credentials of a user that has already a session open:

    

  • Kill Existing Session: Select this option to kill an existing session. When this option is selected, if a user is trying to log in but there is already a session open on another device, the first user that logged into ProcessMaker will lose their session so a new session can be opened on another device.

Click on the Save Settings button to save all configurations made in this section.

It is also possible to make multiple combinations and use both restrictions at the same time. For example, if the following has been set:

The user will be able to log in on the same device, but ProcessMaker will kill the previous session and start a new one each time the user logs in. The user will lose the session if the same login credentials are used on another device.

Password Policy

This option allows users to set the password policy, which sets the guidelines and restrictions for user passwords. To use this option, go to the Enhanced Login tab inside the Admin panel, then click on the Password Policy option in the left panel.

Note: Every time the user logs on ProcessMaker with a different user account, the login window requires the user to change the password only the first time after the password configuration is applied.

The options are detailed below:

• Numeric characters: Enable this option to make sure passwords contain numeric characters.
• Uppercase characters: Enable this option to make sure passwords contain uppercase characters.
• Special characters: Enable this option to make sure passwords contain special characters. Special characters include:

  [ ? / < ~ # `! @ $% ^ & * ( ) + = } |: " ; ' , > {

• Minimum Length: Sets the minimum length of the password. The field will be marked in red if the password set by the user contains less characters than required by this property.
• Maximum Length: Sets the maximum size of the password.
• Password Expiration in (days): Set the number of days the password is valid, so users change it after the specified number of days. If this field is left blank it will be marked in red, because the minimum accepted value is 1.
• Logins Failed: Number of failed logins before setting the user's status to Inactive.

Click on the Save Settings button to save the password configuration.

If the number of attempts surpasses the number set in the Logins Failed field, the following message is shown:

The user's status will be set to Inactive immediately, and only an administrator user will be able to change the user's status.

The failed attempts can be reviewed inside the file named loginFailed.log, which is located at:

Linux:

Windows:

This file contains the date, time, user, IP address, workspace and browser of the last failed attempt. In the example below it is detailed two failed login attempts of a user named Alex.

ProcessMaker v. 2.5.2 (Release date: January 14th, 2014)

ProcessMaker is a cost effective and easy to use open source business process management (BPM) or workflow software application. Workflow software such as ProcessMaker can assist organizations of any size with designing, automating and deploying business processes or workflows of various kinds.

ProcessMaker workflow software features an extensive toolbox which provides the ability to easily create digital forms and map out fully functioning workflows. The software is completely web based and accessed via any web browser, making it simple to manage and coordinate workflows throughout an entire organization - including user groups and departments. ProcessMaker workflow software can also interact with other applications and systems such as ERP, business intelligence, CRM and document management.

ProcessMaker v.2.5.2 is a regular bug-fix release, this document describes its feature enhancements and many bug fixes including the following highlights:

Release date: January 14th, 2014 

What’s new

• Trigger editor improved by adding a pop up when a code needs to be edited. (10870)
• Possibility to customize 404 Not Found and 403 Forbidden Error pages per skin (11603)
• From Name field was added, in order to change the from for notifications sent by the system (11522)
• Improvement when executing workspace-restore command. (13342)

What’s fixed

• Problem sending attach files using PMFSendMessage() function (12375)
• Loosing Email Notification Setting. (11821 )
• Assignment rule is internally modified after changing the case title label (11836)
• When you change the task name the task notification is disabled. (12724)
• Error in Grid dates (12389)

For a detailed description of how to use ProcessMaker please see the wiki page (http://wiki.processmaker.com/index.php/Main_Page).

To see the change log, visit the wiki page: http://wiki.processmaker.com/index.php/Change_Log

To report a bug please go to web page: http://bugs.processmaker.com/

Requirements

For more information of ProcessMaker installation requirements please see the wiki page:(http://wiki.processmaker.com/index.php/Main_Page)

Browser Compatibility

• Firefox v.26
• Chrome V.31
• Internet Explorer v. 8 and 9

New Feature

• 11374: Supervisor is able to reassign cases to himself.
• 11522: From Name field was added, in order to change the from for notifications sent by the system
• 11603: Possibility to customize 404 Not Found and 403 Forbidden Error pages per skins
• 12115: A confirm message was added before printing a dynaform to save edited data.
• 12219: It is possible to claim a case by using the new web service claimCase().
• 12254: In the upper right side of the window, inside a PM Table data, a new search is added
• 12465: It is possible to force Cron execution by using the +force option.
• 13323: A new attribute, inside the suggest field, was added. This determines how searches are performed and the criteria to be used.
• 13508: The "registerCronFile" method was added to be used in the plugins definition, in this way, plugins can register files to be executed.
• 13576: The size attribute was included inside Date fields.

Enhancements

• 9980: Even if you create your process in a different language than the one you are using to edit it, task titles now will appear in the * language you use to create your process.
• 10181: Improved date calculation considering holidays and weekends for due dates and events.
• 10870: Trigger editor improved by adding a pop up when code needs to be edited.
• 11751: Instead of deleting the last row of a grid, its content is deleted.
• 11909: “Conditions Editor” was removed from the grid designer.
• 12029: A new MySQL trigger was added in order to modify the value of the PREVIOUS_USR_UID column, this value will return the user who derives the case.
• 12374: Only Administrator users are able to modify users roles.
• 12434: PDF Compressing files is enabled by default in both libraries(HTML2PDF and TCPDF).
• 12738: Grid Textarea fields weren’t working when they have a query to obtain a data or to execute dependent fields.
• 12749: On new installations env.ini file has been incremented from 128M to 256M.
• 12768: Trigger after InputDocument step executes before input document is saved
• 13342: Improvement when executing workspace-restore command.
• 13383: Hotfixes can now be applied in non standard installation paths
• 13400 Attach files with the same name in an email
• 13425: “AUTH_SOURCE_PASSWORD” field from “AUTHENTICATION_SOURCE” table, has been incremented in size. This change is applied to all RBAC tables.
• 13463: Searches inside Advance Search interface took long. In this version an optimization has been made by adding a new Index (indexAppDelay) inside APP_DELAY table.
• 13506: A new method was added which allows to create a maximum of 5 log files. This avoid the error message displayed when cron.log file is greater than 2GB.

Fixed bugs

• 5120 Change text to clarify the purpose of user for the Case Scheduler
• 5488 Case inbox refresh time should be configurable
• 5720 Can not send Next Task Assignment Notifications with grid variables
• 8500 Checkboxes when creating/editing the structure of PM Tables should be centered
• 8965 Documents download with 0 Kb
• 9869 Users are not able to double click on the input documents; they have to hit the download button to view the input documents.
• 10415 No scroll bar in report table to go left or right
• 10637 Fields validated as "email" do not accept dash (-)
• 10803 Change field from left to right - Right to left
• 10836 It is possible to create 2 workspaces with same name.
• 11075 UP-DOWN option inside triggers is not working
• 11189 When using grids, file names are not saved in the database.
• 11283 Simplified Interface not reflecting minutes
• 11435 Formula field allows to introduce few characters
• 11511 Wrong text in the warning popup message when previewing sent out emails
• 11555 Draft status is not changed when using PMFDerivateCase function
• 11755 User Experience skin is not translated.
• 11786 Updating a process, notifications configured before are set to its default value
• 11788 Notifications email: "Content Type" in "HTML template", doesn’t display "Template" dropdown.
• 11821 Loosing Email Notification Setting.
• 11830: “importProcessFromLibrary()” method was removed.
• 11836 Assignment rule is internally modified after changing the case title label
• 11848 Report table not update when cases were deleted
• 11886 Problems when running a case scheduler event every 5 minutes.
• 11919 Not able to use the product, immediate logout after: error ColumnMap for undefined column: CASE_SUMMARY
• 11934 Problem assigning a position for a checkbox label, it is always displaying at the right side.
• 11994 Date selector returns 1899-12-31 on ProcessMaker 2.5.0.1
• 11998 Spaces added inside the XML of a Dynaform are not displaying.
• 12047 User list is not showing.
• 12054 Problem using PMFDerivateCase function.
• 12059 When 1 trigger is created in a process trigger list of Events is empty
• 12099 Curl Not able to enable
• 12104 Assignment rules changes do not persist when notifications are modified
• 12134 Advanced Search Limits Results
• 12142 Time in the upper right corner remains in '00:00:00'
• 12174 In Internet Explorer, the content of the trigger editor is not displaying correctly and scrollbars of it are missing.
• 12177 Problems in the task names when importing a process.
• 12106 Dynaform submit is not working
• 12112 "caseList" webservice is running a query that crashes ProcessMaker
• 12131 Misspelling in the TinyMCE Editor pmGrids
• 12186 Implementing Autosave Functionality.
• 12171 Continue buttons in view mode
• 12178 Misspelling in a label of the English .po file
• 12189 When calling unpauseCase from a web service twice, the case gets duplicated.
• 12228 Untranslatable strings in processmaker/workflow/engine/methods/setup/languages_Import.php
• 12236 Session problems when using the "PMFNewCase" function
• 12253 When a case is deleted by ProcessMaker, this case is not deleted from the PM Reports.
• 12258 Preview in Messages history doesn't work in IE
• 12261 Case URL used in Task Notification doesn't work correctly
• 12282 Attach documents into emails using original name doesn't work
• 12284 Session is lost when executing PMFInformationUser() function
• 12285 Issue with Input Document with Process Permission
• 12290 Email not being send with Intermediate message
• 12312 The scrollbar and the width is not displaying correctly in the grid.
• 12375 Problem sending attach files using PMFSendMessage() function
• 12387 Grammar Mistakes on English Labels
• 12389 Error in Grid dates
• 12467 When modifying a task property, the assignment rule changes
• 12475 When data is sending by URL, the path is not valid
• 12488 Date fields are editable even when you not select this function and the data fields have to be validate it.
• 12540 No message is displayed when the workspace is invalid
• 12562 Date appears incorrect in the Generated Document List and Input Document List
• 12623 Maximum lifetime cleaned up, option is not defined if is in milliseconds or seconds
• 12624 Problem with the DATA when importing PM Tables.
• 12676 Workspace Restore action from ./processmaker is not working with strange characters.
• 12709 Actions by email: Problems with the approval link
• 12724 When you change the task name the task notification is disabled.
• 12784 Assignment menus inside Triggers (STEPS) are not displaying correctly
• 12876 First level trigger window is overlayed
• 12918 APP_CACHE_VIEW value always displays FALSE value
• 12932 Not validating input text in the designer
• 12986 validateForm() is not working
• 12988 The Resend and Preview is not working in the Message History.
• 12991 Issue with the old version (HTML2PDF)
• 12996 The first line of triggers appears cut at half in neoclassic skin (Mozilla Firefox).
• 13076 Multiple item selection lost for SQL populated listbox
• 13080 When clicking on the( + )icon in the simplified user interface, user cannot see all the processes he can initiate if the processes are more than 10.
• 13122 Problems in the trigger Editor only in Internet Explorer
• 13197 User list is empty when you do an upgrade to 2.5.1
• 13224 Problems with message history.
• 13251 Dynaform dependent fields listbox not working correctly
• 13277 Problem in the Assigning Users to Groups
• 13317 Problems when editing the XML inside the Dynaform designer
• 13321 When editing a PM Table text is changed to TIMESTAMP
• 13324 When ProcessMaker is updated to version 2.5.1, the user name is not displayed.
• 13337 Alphabetical Order in the Country field.
• 13358 ProcessMaker does not redirect to login page, if the session is lost
• 13392 Dependent fields are not showing as selected, but it is assigned in the xml
• 13396 The order action in Message History section is not working fine
• 13397 Required fields in file field, inside a Grid, are not working
• 13399 Text error in trigger wizard
• 13402 SOLR is trying to show the cases list for the PAUSE folder.
• 13421 Filter/Sorting enhancements in the designer processes
• 13428 When 'Copying' a dynaform from another process - Conditions are not copied
• 13436 ProcessMaker 2.x Authenticated PHP Code Execution
• 13450 Cancelling a Case doesn't update to CANCEL status in REPORT table
• 13475 When you get insert a pmconnection into the DynaForm, you get an empty screen
• 13504 Cron gives an error with Case Scheduler
• 13507 Extra columns are creating in grids when hidden fields are created.
• 13528 Error using grids with required fields.
• 13536 Save as option inside a Dynaform is not working.
• 13723 Warning when attaching a document in a Grid.

Known Issues

• 13711 Ordering by dates in the process list is not working
• 13683 Rename option inside documents, has unnecessary alerts.
• 13738 The configuration of the "Adjust the grid width to the width of the main form" option doesn't work in User Experience skin.
• 12819 Cases created using the cron do not insert their reference in the Report Table
• 13811 Unable to activate MSSQL extension through Windows

Languages

Link: http://sourceforge.net/projects/processmaker/files/Translations/

• English (Default core language)
• Spanish (Updated for 2.5.2) 

The ProcessMaker Enterprise Edition v. 3.0.x offers features, performance improvements and plugins compatible with the new BPMN designer. Take into account that the plugins are still being moved/integrated with the enterprise edition of ProcessMaker 3.0. Not all the plugins were moved yet. That's why there is still the need to support both the plugins and the integrated features.

Additionally ProcessMaker 3.0 support both versions of processes the Classic and BPMN. Classic processes only work with plugins and BPMN processes work with features and plugins supported by them.

Current GA Version: 3.0.4 (September 13th, 2016)

1. Resources
   • What's New (3.0.4)
   • Release Notes
   • Old Versions
2. Installation guide
   • Requirements
   • Supported Stacks
   • Supported Browsers
3. Enterprise Feature/Plugins Manager Tool
4. Enterprise Features

   Feature	Open Source	Standard	Corporate	Enterprise
   Core
   BPMN 2.0 Process Designer
   HTML5 Responsive Form Designer
   Output Document Builder
   Basic Dashboards
   Events
   User Portal
   User Management
   Programming
   REST & SOAP APIs
   ProcessMaker PHP Functions
   JavaScript Functions and Methods
   Productivity
   Custom Case Lists
   Actions By Email
   External Registration Wizard Installed as Plugin
   Service Level Agreement (SLA) Monitor Installed as Plugin
   Multiple Input Document Uploader Installed as Plugin
   PowerUp Functions Installed as Plugin
   Batch Routing
   Multiple SendMail Addresses and Servers
   FTP Monitor Installed as Plugin
   User-Based Time Zone Management New! in version 3.0.1.7
   User-Based Language Settings Management New! in version 3.0.1.7
   Add-ons
   Business Rules Installed as Plugin
   Reporting
   Simple Reports Installed as Plugin
   KPIs
   Advanced Dashboards Installed as Plugin
   Connectivity
   Advanced LDAP/AD
   Windows Single Sign On
   Outlook Client Installed as Plugin
   Mobility
   Android & iOS Native Apps	Available in the Android and iOS Market
   Barcode scanner field
   Finger signature field
   Realtime Google Maps
   Photo attachment field
   Video attachment field
   Audio attachment field
   Security and Scalability
   Plugin/Trigger Code Security Scanner
   Advanced Security for User Passwords
   Advanced Audit Log
   Enhanced Login Installed as Plugin
   Promotion Manager New! in version 3.0.1.8
   Performance
   Independent Read and Write Database Management
   Case Archive / Restore Installed as Plugin
   Advanced Performance Monitor Dashboards (*) Installed as Plugin
   Reseller/OEM Features
   Multitenant Manager (**) Installed as Plugin

   (*) Advanced Performance Monitor Dashboards are included in Cloud Only for Gold, and in Cloud & On-Site for Platinum plans.

   (**) Not available in Cloud

Overview

ProcessMaker 3 provides a number of custom JavaScript functions and methods for working with controls in Dynaforms. For more information about how to use custom code in forms, see JavaScript in Dynaforms. Note that these functions and methods are only available in the new responsive Dynaforms used in BPMN processes. If importing an old process from ProcessMaker 2, then use the old JavaScript functions from ProcessMaker 2 to manipulate the Dynaform.

Ways to Access Dynaform Controls

Responsive Dynaforms in ProcessMaker 3 and the libraries they are based upon (jQuery, Backbone and Bootstrap) provide custom methods to interact with Dynaform controls. To use a ProcessMaker method to manipulate a control, first obtain the object for the control, using either a jQuery selector or one of ProcessMaker's custom functions, such as getFieldById(), which are listed below. It is recommended to use ProcessMaker's custom methods to manipulate the controls when possible, because they have built-in error checking when setting the value of fields and are generally easier to use.

Programmers who are more comfortable using standard JavaScript rather than jQuery may wish to access controls using their Document Object Model (DOM) objects, which provide the standard methods. Take into account that these methods are not officially supported, and their use may cause issues when working on ProcessMaker Mobile.

Parts of a Control

ProcessMaker's custom methods refer to 3 parts of a control:

• The label is the text displayed to the left of or above the control to inform the user about the purpose of the control.
• The text is what is displayed to the user in an input field. For textboxes and textareas, the text is the same as the value, but other types of input fields, such as dropdown boxes, checkboxes and radio buttons, have a separate displayed text and a stored value (key) for each option.
• The value is what is entered in an input field and saved when the Dynaform is submitted. The value is the same as the text in fields such as textboxes and textareas, but it is different in fields that have selectable options, such as dropdown boxes, checkboxes and radio buttons, where the visible text is different from the internal value (key) that represents an option.

Obtaining jQuery Objects

A jQuery object can be obtained for each control in a Dynaform. This object contains the standard jQuery methods, such as hide() and show(), but it also contains custom methods added by ProcessMaker. It is recommended to use these custom methods, which are listed below, when manipulating Dynaform controls.

jQuery("#id") or $("#id")

All the controls in a Dynaform, including textboxes, titles, labels, links, images, etc., have an ID that can be used to obtain the jQuery object that ProcessMaker uses to manipulate a control. To obtain this object, use jQuery's selector method to access the control using its ID. $ is an alias for jQuery, so the selector method can be called either way:

jQuery("#id") or: $("#id")

This selector will return an object that has methods to manipulate Dynaform controls, such as getValue(), setValue(), getLabel(), etc. These methods can be called once the control object is obtained.

Example:

Note: Panel controls before version 3.0.1.5 did not have an ID, so it is not possible to use $("#panel-id") to obtain a panel object before version 3.0.1.5.

The # is used to find an element in the current frame with the specified ID. A control's ID identifies the outer <div> which holds the control, so calling $("#control-id") will return an jQuery object for that div, which contains some custom methods to manipulate the control. See the sections below if needing to access the input field or label for a control.

To use a jQuery selector to search for a style class, use a . (dot) followed by the class name. For example to search for all elements which use the "textLabel" class:

Likewise, it is possible to search for a tag. For example, to search for all the <span>s tags in the Dynaform:

To search for the elements containing a particular attribute, use "[attributeName=value]". For example, to search for a name of "clientId":

All of these searches can be combined. For example, to search for a <label> using the "control-label" class whose for attribute is set to "clientId":

The DOM objects for all the elements which were found by a selector are placed in an array in the jQuery object. To find out how many elements were found by the selector, check the length property of the jQuery object that is returned. For example, to make the text the color green in the first and last <span>s found by a selector:

Many jQuery methods, such as show(), hide() and css(), will operate on all the elements returned by the selector. These methods return an array of all the elements they operated on. A few jQuery methods such as attr() will only operate on the first element returned by the selector.

The jQuery selector $(DOMobject) can also be used to convert a DOM object into its jQuery object.

Example:

Note: The value of a control should only be changed using setValue() or setText(). It should not be changed by setting its value property, because that will not set the value in the hidden field for each control, nor will it change its value in the controls' Backbone object, so it will not be saved correctly when the Dynaform is submitted.
NEVER do this:

Accessing Forms

The jQuery object for a Dynaform's <form> can be accessed by specifying the 32 hexadecimal character unique ID which ProcessMaker automatically generates for it.

$("#dynaform-uid")

Example:

Accessing Controls in Subforms

The controls in subforms can be accessed just like normal controls, as long as their IDs are unique. If a control in a subform has the same ID as a control in the master form, then first obtain a subform's jQuery object using its 32 hexadecimal character unique ID which ProcessMaker automatically generates for it. Then, use jQuery's find() method to search for the control's ID inside the subform.

$("#subform-uid").find("#control-id")

Example:

Standard jQuery Methods

In addition to the custom ProcessMaker methods added to the jQuery objects for controls, jQuery also provides a library of standard methods which can be used to manipulate the controls. Listed below are some of the more useful ones frequently used in the examples on this page.

.attr()

.attr() is a standard jQuery method that gets and sets the value of attributes in elements. If the jQuery selector returns more than one element, it gets or sets the attribute of the first element.

To get the value of an attribute:

$("#id").attr("attributeName")

To set the value of an attribute:

$("#id").attr("attributeName", "value")

Attributes are the values of an element that are usually defined in its HTML definition and are usually set before it is rendered on the screen. In contrast, properties are the values of an element that are usually set when it is added to the the DOM and rendered on the screen. Unlike attributes, which usually do not change and are fixed in the initial definition, properties often can be changed by the user. Attributes should be accessed with .attr(), whereas properties should be accessed with .prop().

In the above example, id, type and value are attributes defined in the HTML code, but align, autofocus, and baseURI are properties set when the element is rendered. For most values, it doesn't matter whether they are accessed with .attr() or .prop(), but it can make a difference in some situations.

For example, if the user changes the value of this textbox from "Acme, Inc." to "Wiley Enterprises", calling:

This code will return "Acme, Inc.", which was the initial value and is now fixed. However, calling:

This will return "Wiley Enterprises" which is the current property and can be changed.

Examples:

.show()

show() is a standard jQuery method that can be used to show a control and its label in a Dynaform. Other controls will be moved down or to the right. It does this by setting style.display="" in the outer DIV, which holds the control and its label.

$("#id").show()

Return Value:
Returns an object that holds information about the control. For example, a textbox with the ID "lastName":

.hide()

hide() is a standard jQuery method that can be used to make a control and its label disappear in a Dynaform. Other controls will be moved up or to the left to take its place. It does this by setting style.display="none" in the outer DIV, which holds the control and its label.

$("#id").hide()

Return Value:
Returns an object that holds information about the control. For example, a textbox with the ID "lastName":

Example:

.css()

css() is a standard jQuery method that can be used to either read or change one of the style properties of a control.

To read a style property:

var x = $("#id").css("propertyName")

To change a style property:

$("#id").css("propertyName", "value")

Note: Style properties in JavaScript and DOM use camel case, whereas CSS uses lowercase with words separated by hyphens (-), but .css() can understand both styles, so .css("background-color") and .css("backgroundColor") are the same.

Example:

Searching for Elements

jQuery provides a number of methods to search for elements, which are similar to the jQuery selector function $(), but they start their search based on where the element is in the Document Object Model (DOM) tree. Some of the more useful methods include:

• .find() searches within all the descendant nodes in the DOM.
  Ex: Get the label of the "companyName" field: $("#companyName").find("span.textLabel")
• .children() searches just within the child nodes.
  Ex: Get all the rows in a Dynaform with the ID "3088873965642528e4073a7021293108": $("#3088873965642528e4073a7021293108").children("div.row")
• .siblings() searches within the siblings nodes in the DOM.
  Ex: Get all the controls in the same row as the "companyName" field: $("#companyName").siblings()
• .closest() searches for the closest matching element in the DOM.
  Ex: Get the form for the "companyName" field: $("#companyName").closest("form")
• .first() gets the first among the elements returned by the initial selector.
  Ex: Get the first textbox in the form: $("div.pmdynaform-field-text").first()
• .eq(index) gets a specified element from the array of elements returned by a selector. The index starts counting elements from the number 0.
  Ex: Get the fourth textbox in the form: $("div.pmdynaform-field-text").eq(3)

Backbone Objects for Controls and Forms

Backbone.js is a library that provides the model for Dynaforms and their controls. ProcessMaker offers three custom functions getFieldById(), getFieldByName() and getFieldByAttribute(), which are used to obtain the Backbone objects for Dynaform controls. In addition, the getFormById() function is used to obtain the Backbone object for the Dynaform.

The Backbone object supports most of the custom methods for manipulating controls, such as control.getValue(), link.setHref(), grid.getNumberRows(), plus it offers the setFocus() method which is not provided by the jQuery object.

Functions to Obtain Backbone Objects

getFieldById('id')

The getFieldById() method returns an object that is generated by Backbone to manipulate the controls in a Dynaform. Its properties can be used to access the outer DIV for a control, which is used to resize controls when a form's width changes.

window.getFieldById("id")

Parameter:
id: The control's ID.

Return Value:
Returns a Backbone object whose properties may vary according to the type of control and whether the control has a variable assigned to it. All input controls should have the cid, $el, el, model, parent and project properties. A textbox which has a variable assigned to it has the following content:

Inside the returned Backbone object, the $el property is the jQuery object for the <div> that encompasses the outer <div> of a Dynaform control. Likewise, the el property is the DOM object for the <div> that encompasses the outer <div> of a Dynaform control.

For example, here is the HTML structure of the "company" textbox control that uses the companyName variable:

Calling getFieldById("company").$el returns the jQuery object for the outermost <div> without a class name, whereas calling $("#company") returns the jQuery object for the outer <div class="...pmdynaform-field" ...>. To get to that same outer <div> with the Backbone object, use: getFieldById("company").$el.children()

Examples:

getFieldByName('name')

getFieldByName() searches for control(s) by the name of the variable used by the control and returns an array of matching Backbone object(s).

window.getFieldByName("name")

Parameter:
name: The name of the variable used by a Dynaform control. Set to "" (an empty string) to search for all the controls that do not have an assigned variable.

Return Value:
Returns an array of the Backbone object(s) for the control(s):

getFieldByName("name")[0] returns the same object as getFieldById("id"), so its $el, el, and other properties can be accessed in the same way.

Example:

getFieldByAttribute(attr, value)

The getFieldByAttribute() method searches for controls whose attribute matches a specified value.

window.getFieldByAttribute(attr, value)

Parameters:
attr: The name of a attribute. See the object below for all the available attributes.
value: The value of the attribute to search for.

The attributes for a control can be found in the getFieldById("id").model.attributes object, which can vary according to the type of control. See this list of the available attributes for controls.

Return Value:
Returns an array of all the Backbone control objects that match the search attribute. The properties of each object vary according to the type of control.

Remember that the $el and el properties are for the outer DIV. To access the inner DIV, use getFieldByAttribute(attr, value)[i].el.childNodes[1]. To access the input field for a control, use: getFieldByAttribute(attr,value)[i].$el.find("input"), but the hidden input fields will need to be ignored. To find only textboxes and textareas use: getFieldByAttribute(attr,value)[i].$el.find(".form-control")

Example:

getFormById('id')

The getFormById() method returns the Backbone object for a Dynaform.

window.getFormById("id")

Parameter:
id: The Dynaform's unique ID, which is 32 hexadecimal characters. It can be obtained by clicking on the border of the Dynaform to see its id property.

Return Value:
Returns a Dynaform object, with content such as:

The object that is returned contains the $el object, which allows access to the form's jQuery methods and properties. Use the el object to access it as a normal form object. For example, getFormById("id").el.submit() can be used to submit the form. getFormById("id").el.reset() can be used to reset the form back to its original values. getFormById("id").el.length is the number of inputs in the form and getFormById("id").el.elements is an array of those inputs.

Example 1:

Methods and Properties in Backbone Objects

Apart from the custom methods to manipulate a control, the Backbone object holds the control's model information at:

getFieldById("id").model

The control.model.attributes is an object with all the attribute properties of the control and the control.model.keys() method can be used to obtain an array of the attribute names used by a control.

The .$() method in the Backbone object is a jQuery selector which searches for elements inside the control. For example, to obtain the "companyName" control's label:

Methods for Controls

The following are custom methods provided by ProcessMaker to manipulate controls. All of these methods except for setHintHtml() are available in both the jQuery and Backbone objects for the control, so they can either be called with $("#id").method() or getFieldById("id").method() (or one of the other 3 functions to obtain Backbone objects).

control.getLabel()

The getLabel() method returns the label of a control in a Dynaform.

$("#id").getLabel()

Note: This function does not work with panel controls since they do not have labels. Before version 3.0.1.3, this function was not available for radio controls.

Example:

control.setLabel()

The setLabel() method sets the label of a control in a Dynaform.

$("#id").setLabel("newLabel")

Note: This function does not work with panel controls since they do not have labels. Before version 3.0.1.3, this function was not available for radio controls.

Note: Calling setLabel() for a title, subtitle, button or submit control will reset its properties and remove any custom properties set by JavaScript. After calling setLabel(), these properties will need to be reset.

Example:

Note: The text of the new label may contain HTML entities such as > for < and € for €, but HTML tags, such as <em> and <br>, will be treated as normal text. To format a control's label, first use use jQuery's /.find() method to search for the <span> with the "textlabel" class inside the control. Then, use its .html() method to add HTML code to the label.

Example:

control.getValue()

The getValue() method returns the value of an input field in a Dynaform.

$("#id").getValue()

Return Value:

The value returned by this function depends upon the type of control:

• For textboxes, textareas and suggest boxes, this function returns the text entered into the field.
• For input fields which have selectable options, such as dropdown boxes and radio buttons, it returns the internal value (key) of the selected option.
• The value returned for checkboxes/checkgroups changed in version 3.0.1.4 and later. See Getting values in checkboxes/checkgroups below.
• For datetime fields, it returns the entered datetime in standard YYYY-MM-DD HH:MM:SS format.
• For file fields, it returns the filename of the selected file. If there is no selected file, then getValue() returns [] (an empty array).
  Warning: The file control's value is not consistent, it might return an empty array, empty string, array of uid, file name or fake path. This is a known issue that will be fixed in future releases.
• For links, it returns the displayed text for the hyperlink.
• For images, it returns the URL to the image file.
• For titles, subtitles, and labels in version 3.0.1.3 and later, it returns their text.
• For submit and generic buttons, it returns the text displayed in the button.
• For grids in version 3.0.1.4 and later, it returns an array of arrays where the outer array holds the rows in the grid and the inner arrays hold the values of the fields in each row. See Getting values in grids below.
• Note: This method does not work with panels.

Example - Searching in a textarea:

Example 1 - Checking for a selected value in a dropbox:

Example 2 - Checking for selected value in a dropbox:

Checkboxes/Checkgroups

Before version 3.0.1.4, a checkbox could be based upon a string, boolean, integer or float variable and it contained as many checkable boxes as the number of options, so it could be a single checkbox or a group containing multiple checkboxes. In version 3.0.1.4, checkboxes were changed to only use boolean variables and only allow one checkable box. In the same version, checkgroups were added for controls that need multiple checkable boxes and they only use array variables.

Checkboxes before v3.0.1.4 and checkgroups

The $("#id").getValue() method for checkboxes before version 3.0.1.4 and checkgroups after version 3.0.1.4 returns a JSON string which contains an array of the values (keys) of the selected options. If no options were selected then it returns a JSON string containing an empty array. If one checkbox is marked, it returns an array with one value

Example 1:

Example 2:

Checkboxes in v3.0.1.4+

Checkboxes in version 3.0.1.4 and later are based upon boolean variables and can only contain a single checkable box. getValue() returns "1" if the checkbox is marked and "0" if unmarked. Its text label is set in its options when creating the boolean variable, but if not set, then it is "true" by default.

Example 1:

Example 2:

control.setValue()

The setValue() method sets the value of an input field, sets the source URL of an image, or sets the displayed text of other types of controls in a Dynaform. The way a field's value is set depends on the type of field. In HTML, all numbers are treated as strings, so numbers will automatically be converted to strings when they are set as the value of a field.

For controls that only have a single value, such as a textbox, textarea, suggest, dropdown box, radio button, datetime, hidden, the src in an image, or the displayed text in a title, subtitle, label, link, generic button or submit button:

$("#id").setValue("value")

For checkgroups in version 3.0.1.4 and later, which can have multiple selected options:

$("#checkgroup-id").setValue(["value1", "value2", ...])For grids in version 3.0.1.4 and later: $("#gridId").setValue("value", row, col)

setValue() does not work with panels, subforms and files. To set the contents of a panel, use code such as:

Warning: Calling setValue() for a title, subtitle, button or submit control will reset its properties and remove any custom properties set by JavaScript. After calling setValue(), these properties will need to be reset.

Textboxes and textareas:

For textboxes and textareas, enter a new value that will be set in the field.

$("#id").setValue("value")

For example, to set the value of a field with the ID "contractDescription":

Use \n to insert a new line and \t to insert a tab in a textarea. For example:

Example:

Suggest, dropdown boxes and radio buttons:

Checkboxes before version 3.0.1.4:

Before version 3.0.1.4, a checkbox could be based upon a string, integer, float or boolean variable. It contains as many checkable boxes as the number of its options and multiple options could be selected. The setValue() method can be used to set which checkboxes are marked (selected) by passing it an array of values to select in the checkbox. Remember that the value(s) are the key(s) for the selected option(s), not the label(s), which is the text displayed to the user:

$("#id").setValue(["value1", "value2", ...])

Example:

Checkboxes in version 3.0.1.4 and later:

In version 3.0.1.4, checkboxes changed and can now only be based upon boolean variables and only have one checkable box. To mark (select) a checkbox, set its value to "1". To unmark (deselect) a checkbox, set its value to "0".

Example:

Checkgroups in version 3.0.1.4 and later:

Checkgroups were added in version 3.0.1.4. A checkgroup is a group of checkable boxes and it is based upon an array variable. It contains as many checkboxes as the number of its options and multiple options can be selected. The setValue() method sets which checkboxes are marked (selected) by passing it an array of values (keys) which are to be marked. Remember that the value(s) are the key(s) for the selected option(s), not the label(s), which is the text displayed to the user:

$("#id").setValue(["value1", "value2", ...])

Example:

Datetimes:

To set the value of datetime fields, enter the datetime in ISO-8601 format, such as "YYYY-MM-DD" for dates or "YYYY-MM-DD hh:mm:ss" for datetimes, where YYYY is the year, MM is the month between 01 and 12, DD is the day between 01 and 31, hh is the hour between 00 and 23, mm is the minutes between 00 and 59, and ss is the seconds between 00 and 59. Remember that months, days, hours, minutes and seconds must be expressed with two digits, so the first second of the year 2016 is "2016-01-01 00:00:00".

Example:

Links:

Link fields contain both the URL and the label (the text displayed to the user). Use the link.setHref() method to set the URL of a link field and the control.setValue() method to set the label of the link, which is displayed to the user.

Example:

Submit and generic buttons:

The setValue() method can be used to change the text displayed inside buttons.

Example:

Grids:

For grids, please check out the following documentation: grid.setValue()