WebToolz (previously called FormToolz) makes it quick and easy to add dynamic user-interactive components to iMIS pages. Being an iPart, it works well in conjunction with all other iParts (e.g Content Collection Organiser). It combines drag and drop user-interface design with the ability to process complex business logic in SQL stored procedures..
Important Terms and Definitions
To fully understand the WebToolz iPart, it is helpful to be familiar with some core terms and definitions.
- Controls—These are a list of components or tools you may use to build your web pages. Controls are broken into three categories:
- basic form controls - these are controls typically found in form builders such as: text boxes, dropdown boxes, combo boxes, and radio buttons. These types of controls can be executable controls which do something, like fire a stored procedure, or what we call smart HTML controls, which are the normal form builder type of controls with some additional data-driven elements (like show or hide business logic), Pre-process (executed before the page loads).
- extension controls - allow you to change a password, assign a password, download or upload a file, or perhaps send an email. These are typically termed post-execution controls because they do something special after the execution of the form you are on.Other extension controls include integrations to other pieces of software (e.g Adobe Connect or Canvas LMS), or tools to facilitate integrations (Like single sign on and API wrappers). Some of these extensions controls are charged for separately (indicated by the PLUS icon after their name.
- Analytic controls - these controls enable web analytics by allowing you to capture a user’s browser type, browser platform, IP address and the URL they are accessing.
There are three different types of parameters used with the WebToolZ iPart. Whether a parameter is seen as an inbound parameter or an outbound parameter is always based from the vantage point of how the parameter works with the object of your focus. For example, when considering one of your own SQL procedures, the inbound parameters are ones you send to your procedure and the outbound parameters are the ones you send from your procedure. When considering the WebToolz iPart, the inbound parameters are ones coming from, say, a URL into the iPart or from your custom SQL procedure into the iPart and it has no outbound parameters. In the case of the iPart, it so happens that the outbound parameters of your procedure are the inbound parameters for the iPart. This explained, there are three types of parameters: URL, inbound and outbound.
- Inbound Parameters—Inbound parameters are ones captured by a form or page and then sent to your custom SQL procedure where sone business logic is applied and the parameters are written to iMIS.
- Outbound Parameters—Outbound or return parameters are ones sent out of your custom SQL procedure, and may appear on a web page, alter a web page or create an action (like a redirect, file download, or sending an email.
- URL Parameters—URL parameters are ones located in the URL of the webpage being visited. In this examplehttp://www.zengage.co/index.asp?Page=Example the URL parameter immediately follows the question mark and ends just before the equal sign—here, the word “Page” is the URL parameter. It is also possible to have parameters after the question mark and these are delimited by use of the ampersand (&) and the equal sign. In this example http://www.zengage.co/index.asp?Page=Example¶graph=3&sentence=5 the word “paragraph” is the second parameter and the word “sentence” is the third parameter. Each of these is assigned the value immediately after the equal sign, making the value of Page = “Example”, the value of paragraph = “3” and the value of sentence = “5” as noted in the example above.
- These URL parameters may be used as incoming parameters in the iPart and assigned as pre-populated values that display when the control is rendered to screen.
- These URL parameters should be entered without a leading @ sign, which makes their use different than the incoming parameters from your SQL procedure which require the use of the @ so that the iPart may recognize the difference between the two.
The Zengage WebToolz iPart operates under the following foundational principals.
First, every time the iPart is used to interact with the iMIS database, it must be associated with an SQL stored procedure—the iPart only acts upon data it is offered from outbound parameter values returned from your SQL procedure. As an example of this, consider the ResetPassword control of WebToolz explained in much greater detail later in this manual. WebToolz can create a username and password for an existing contact when you return the iMIS ID, a username and password to WebToolz via the outbound parameters of your custom procedure. The workflow to produce this expected result is as follows: drop an instance of the WebToolz iPart on a content page; choose the ResetPassword operation; create a procedure that returns the ID, username and password, associate your procedure to the iPart; build the form; and run the form.
Second, all internal iMIS business rules must be respected when operating the iPart against the iMIS system. An example of this when using the ResetPassword operation is that the username may not already be in use; the password must meet password restrictive rules established in iMIS; the contact must already be made or must be made in your custom procedure prior to returning the outbound parameters to the iPart; and an email address must already be assigned to the contact record.
Third, iMIS macro variables such as @CurrentUser, @Me, @Now may not be used as incoming parameters or outgoing parameters as these are filled in by the iMIS subsystem and this iPart is external to that. Further, the @ sign is reserved for use in defining incoming parameters from SQL procedures, which means that all URL parameters are used in the iPart without the leading @ sign.
To provide a quick overview, one simple example of how WebToolz can enhance your web content functionality is presented in the following video. It shows how you can build the functionality to enable file uploads and downloads from your servers and get download statistics.
Once installed, WebToolz components or iParts can be added to any web page content in the iMIS using the Content Designer tool. In the Content Designer window, click on 'Add content' and select Zengagers -> FormToolz from the Content Gallery. This will add the WebToolz component to your page and open up a 'Configure iParts - FormToolz' window where you can design and configure your user interface controls and link them up with backend SQL script and stored procedures. These steps are illustrated in the screenshots below.
1. Create a new 'Website Content' in the Page Builder.
2. In the Content Designer window, click on 'Add content' and select Zengagers -> WebToolz from the Content Gallery.
3. WebToolz component is now added to your page and a 'Configure iParts - WebToolz' window is opened up where you can design and configure your user interface controls and link them up with backend SQL script and stored procedures.
In the 'Global settings' tab of the configuration window, you can select settings that will be effective for the whole iPart component (and not just for individual controls within the component). Most importantly, you can provide the parent CSS class that will define the style for elements within your iPart and you can select whether or not you are going to use a SQL stored procedure to process your form when it is submitted to the server.
In the 'Controls' tab of the configuration window, you will select and configure WebToolz controls and design your user interface. You will also configure how your selected controls communicate with the SQL stored procedure on the backend server. The screenshot below gives an example of the options for configuring a Checkbox list control after it has been selected and added to the WebToolz iPart.
In the 'CSS' tab of the configuration window, you can define CSS styles that should be applied to specific WebToolz controls or those applied to the entire iPart. Each control has a configuration parameter where a CSS class can be specified (see the discussion later of control configuration parameters). The screenshot below shows the definition of CSS styles for the iPart CSS class "my-form-css", as an example. In a similar way, other CSS style definitions can be created here which correspond to the CSS classes specified for specific WebToolz controls.
The usage of configuration parameters common to many controls is outlined in the table below.
|Caption||Provides a label or description for the form control.|
|Position of caption||Determines how to place the caption relative to the form control. The possible options are: Bottom, Left, Right and Top.|
|Required||When checked, places a red asterisk (*) in front of the control to signify that the user must provide a value for the control before the form can be processed by the application.|
|Line break||Places the control in a new line.|
|CSS class||Provides the name of the CSS class which can be used to style the specific control. The style definitions can be added in the CSS tab of the iPart configuration window.|
|HTML5 Data Attributes||Allows you to enter an HTML data attribute that is generated in the code, allowing you to use your own language-specific associations with generated objects. Enter the data into this field in the following format: data-animal-type="bird"|
|Pre-populate via URL parameter||Populates the control with the value received from the URL parameter defined in this field.|
|Pre-populate via IqaQuery||Sets the control to the value obtained from the specified field of the first record returned by the IQA query. In the configuration, the source field is separated from the path of the IQA query by a semi-colon. Example: $/Zengagers/Contact;ID|
|Programmatically Show & Hide||Shows the control if the specified IQA query returns one or more records; otherwise, the control is hidden.|
|Stored procedure||Assigns the stored procedure which expects to receive input values from the control.|
|Stored procedure parameter||Assigns the parameter name which will be used by the relevant stored procedure to receive input values from the form control.|
|Type of values||
Relevant to controls that display a list of options to choose from - in a Dropdown list, Checkbox list, Radio button list, and Multi-select list. Three different sources of data can be defined for this control type:
|Length||Limits the length of characters allowed in fields such as the Textbox and the Datepicker.|
Note that it is important to click on 'Update Control' if you want to save the configuration changes you have made for each individual control.
WebToolz offers a number of useful controls to build interactive web components. These controls can be put into conceptual categories.
- Execute Controls - these are controls that fire when you hit a submit button, or on a specific event (like a page load or a post to the database
- Smart HTML controls - These are your standard form-builder controls (like checkboxes and drop-downs) with a few additional ones that are able to respond to business logic - like conditional drop-downs or conditional show/hide elements. There are also a few user account driven ones like changing passwords, and data driven ones - where an IQA query controls what is on the page.
- Pre-Process Controls - these are controls that pick up data before processing - like getting the ID of the logged in user, or what is in the cart.
- URL and tracking - these controls can either give you information on the current user - like their browser, IP or device, or they can redirect the user to another web page after submission.
- PLUS controls - these controls require an additional license and are generally integration controls for other software solutions (Like adobe connect).
The controls are explained in a bit more detail below.
Change password by username
This control can be used to reset the password for the logged in user. It will pass values for @UserId (the user ID of the person logged in) and @Password (a randomly generated password) to the stored procedure selected in the 'Stored Procedure' configuration parameter. The selected stored procedure must define its input parameters for receiving user ID and password as @UserId and @Password.
The Dropdown Control is one of the most versatile controls for creating forms. As a standard dropdown box in a form it can allow users to either
- select values from a designated list of comma-separated display;value pairs (NOTE - the pairs should have semi-colons between them and be separated by commas, eg one;1,two,2)
- select a value designated by an IQA query - NOTE - the results must display just two columns called value and text
This control can also be used for conditional dropdowns - where based on the answer to a previous question, the available fields in a drop-down can be changed. This uses the Control ID parameter at the top of the control's setting. By placing IQA:yourcontrolID into an IQA filter which is used to display values for the child dropdown, the IQA list is tailored based on the parent dropdown's answer. For more information on this, see this post
NOTE - you will need to [check] the Activate as trigger for dependent drop-downs and use selected value as filter for IQA queries checkbox in order for conditional dropdowns to work
This control enables you to select multiple IDs from an IQA query and pass them through to your stored procedure as a list of comma-separated values.
- the query will need to have the ID column prefixed with 'key_' in the alias in order that this control knows which column to take the IDs from.
- You can decrypt data in a query using the decrypt checkbox
Example Stored Procedure
CREATE PROCEDURE [dbo].[Zen_AddActivity]
-- Add the parameters for the stored procedure here
--IqaQuery: Choose who who will be getting the activity
@ListIDs nvarchar(max) = '',
--DropDown: Activity Description
@ActivityNote nvarchar(max) = '',
--Date: Effective Date
@Date DateTime = null,
@ReturnMessage AS varchar(max) = '' out
DECLARE db_cursor CURSOR FOR SELECT Element FROM asi_SplitString(@ListIDs,',')
DECLARE @id varchar(10)
FETCH NEXT FROM db_cursor INTO @id
WHILE @@FETCH_STATUS = 0
DECLARE @ACTSEQN AS INT
EXEC dbo.sp_asi_getcounter2 @CounterName = N'activity', @CounterValue = @ACTSEQN OUTPUT
INSERT INTO Activity (SEQN, ID, ACTIVITY_TYPE, TRANSACTION_DATE,EFFECTIVE_DATE, DESCRIPTION)
VALUES (@ACTSEQN, @id, 'ACTIVITY1', getdate(), @Date, @ActivityNote)
FETCH NEXT FROM db_cursor INTO @id
SET @ReturnMessage = 'New Activity Created.'
This control is used to generate a new password based on configured criteria such as the 'Number of Alpha-numeric characters' and the 'Length of password'. The name of the stored procedure parameter which will receive the password value can be configured here (unlike when using the 'Change password by username' control).
This control will call the stored procedure defined in its 'Stored Procedure' configuration parameter when the form is submitted (or posted back) to the server.
This control executes a stored procedure defined in its 'Stored Procedure' configuration parameter as soon as the web page finishes loading in the user's browser.
Download a file on initial load
This control triggers a file download as soon as the web page finishes loading in the user's browser. It relies on receiving values for the parameters @Byte, @Name and @ContentType from the stored procedure defined in its 'Stored Procedure' configuration parameter. Hence, the configured stored procedure must return values for its output parameters that are named @Byte, @Name and @ContentType.
Download file button
This control when clicked will call a stored procedure defined in its 'Stored Procedure' configuration parameter. The configured stored procedure is expected to return values for the parameters @Byte, @Name and @ContentType as its output parameters.
declare @JSOut nvarchar(max);
set @JSOut = 'jQuery("#id").html("<div>This is a sample sentence that isn't properly escaped.</div>");'
If you note the SET command above, you'll see that the word "isn't" contains a single quote. This defies proper SQL coding. Properly coded for return from your stored procedure, you want to escape the single quote, so your code would look like this:
declare @JSOut nvarchar(max);
set @JSOut = 'jQuery("#id").html("<div>This is a sample sentence that isn''t improperly escaped.</div>");'
declare @JSOut nvarchar(max);
, @SQLResult nvarchar(10);
select top 1 @SQLResult = FieldValue where table.field = 'Condition'
set @JSOut = 'jQuery("[data-attributename$=''FirstName"]'').val("'+@SQLResult+'");'
In this example, please note that the single quote begins and ends the SQL text string to be returned in the @JSOut variable. Also, note that the escaped single quote (i.e. two single quotes back to back -- '' ) are being used inside the parenthesis for the jQuery clause. Also note that the val() function of the jQuery call includes double quotes before and after the +@SQLResult+ portion of the statement because we need to concatenate the value of the @SQLResult variable and not send the @SQLResult variable itself.
Send an email
This control directs WebToolz to send an email through the mail server. The stored procedure defined in the control's 'Stored Procedure' configuration parameter must set relevant values for its output parameters: @To, @CC, @BCC, @Sender, @Subject, @Message. Setting values for @CC and @BCC is optional.
The TextBox is one of the most versatile controls for creating forms. As a standard text box in a form it can allow users to enter any range of data. It is notable that in HTML, all data is transferred to the underlying SQL stored procedure as text and must be formatted and validated once on the server. While you can force formatting in many ways on the client, the data type itself is assigned on the server.
Specific attributes to this object are:
- caption -- the text being displayed to the user describing what data the text box holds
- length -- the maximum length you will allow data to be entered in characters
- filter -- offers the ability to force specific data values and/or formats. Examples of filter text values you may mix, match and of which you may enter multiple values into the "filter" field are:
- Allow only Numbers i.e. Digits 0 – 9
- Enter filter: Number
- Allow only Alphabets (Both Uppercase and Lowercase)
- Enter filters: LowercaseLetters, UppercaseLetters
- Allow only Uppercase Alphabets
- Enter filter: UppercaseLetters
- Allow Alphabets and Numbers(Alphanumeric and no special characters)
- Enter filters: Numbers, UppercaseLetters, LowercaseLetters
- Email Address(Lower case alphabets, numbers, @ and dot)
- Enter filters: Numbers, LowercaseLetters, Custom
- Valid Chars: .@
- Allow only Numbers i.e. Digits 0 – 9
- read only -- sets the field to read-only and grayed out at the object level
- programmatically show/hide -- insert the path to an IQA query in this field and if the query returns any results, the field will show; if no records are returned, the object will not display
- display caption and line break -- separates the text box from the associated label
- css class -- a class that is identified on the CSS tab of the iPart. Be certain to enter the CSS class with out the preceding period (.) in front of the class name
- HTML5 data attribute -- completely self-defined data attribute and value for this text box object. The field should be entered using the following format: data-attribute-name="AttributeValue"
- Please be certain to enter the value including the data- prefix and include the equal sign with a value
- pre-populate via URL parameter -- allows the value of a parameter in the URL to move directly into the field when the form is loaded. The URL is examined for &var=val or ?var=val where "var" represents your variable and is the text you enter into this pre-populate via URL parameter field, and where "val" is the value that will appear inside this field when the form is loaded
- pre-populate via IQA query -- allows you to return a value from an IQA query that is formatted to return a single row with two fields:
- this field should hold the full path to Iqa query with field containing setting separated by semicolon e.g. $/Common/Test;ID.
- Insure that there is a single row returned
- In the example above, the IQA $/Common/Test will run at form load and the value in the ID field returned as a pre-population value for the form
- decrypt data -- if marked, the ASI encryption algorithm is executed over the data before being displayed on screen
- stored procedure -- the stored procedure to which this text box data will be sent when called from the iPart. This procedure is established by including some kind of execute object such as a button or on-form-load execute object. Once you identify the stored procedure in an execution object, it will appear as an option in this dropdown
- stored procedure parameter -- the name of the parameter to be sent to the stored procedure. This field must have a value prefixed with an @ sign.
- Note: All stored procedure parameters must be prefixed with an @ sign and all URL parameters must NOT have the @ sign.
This control enables passing of values between the web page and the configured stored procedure through the use of URL parameters. To be able to receive values passed in the URL parameters, the stored procedure must define an input parameter corresponding to the name defined in the 'Stored Procedure Parameter' field. Note that the field 'Url Parameter' defines the name of the parameter as it appears in the URL. WebToolz then assigns the value held in this URL parameter to the input parameter defined for the stored procedure in the 'Stored Procedure Parameter' field.
This control directs WebToolz to load the web page with the URL value passed to it by the stored procedure defined in its 'Stored Procedure' configuration parameter. The corresponding stored procedure must define an output parameter with the name configured in the 'Stored Procedure Parameter'. This output parameter's value must be set to a URL string (eg. http://www.zengage.rs) where the user will be redirected to by WebToolz.
Web analytics controls
WebToolz can also collect information useful for web analytics and pass it on to the database and SQL stored procedures. This information can help analyze member specific engagement with the online content and also gauge the response of individual members to online campaigns, promotions and events.
The web analytics controls provided by WebToolz are: Browser Name, Browser Platform, Browser Type, Browser Version, User Agent (Browser), Get IP address of visitor, Logged in user, and Url (records the web page URL).
Each of these controls requires the name of the stored procedure it should pass its value to (as defined in the 'Stored Procedure' configuration field) and the name of the input parameter in the stored procedure which will hold its value (as desfined in the 'Stored Procedure Parameter' field). The screenshot below shows an example of the configuration parameters for the 'Logged in user' control.
Note: In the instructions below, replace <IMIS_INSTALLATION> with the root path of your iMIS installation.
- Import "FormToolz Content Type.xml" in the Staff view through RiSE -> Maintenance -> Content Types
- Drop folder "Flexible Formz" in the folder "%iMIS Installation%\net\iParts\Zengage" e.g. C:\Program Files (x86)\ASI\iMIS\Net\iParts\Zengage
- Drop file "Zengagers.FlexibleFormz.dll" in the folder "%iMIS Installation%\net\bin" e.g. C:\Program Files (x86)\ASI\iMIS\Net\bin
- Drop file "Zengagers.FlexibleFormz.dll" in the folder "%Asi.Scheduler%\bin" e.g. C:\Program Files (x86)\ASI\iMIS\Net\bin
- Add following binding to your web.config file in iMIS under:
Version 20.1.4 ... none needed
Version 20.1.19 - 20.2.1
<assemblyIdentity name="Telerik.Web.UI" publicKeyToken="121fae78165ba3d4" />
<bindingRedirect oldVersion="2012.2.607.40-2013.3.1114.45" newVersion="2014.1.403.45" />
<assemblyIdentity name="Telerik.Web.UI" publicKeyToken="121fae78165ba3d4" />
<bindingRedirect oldVersion="2012.2.607.40-2014.3.1024.45" newVersion="2014.3.1209.45" />
- Replace the following section in the web.config to allow HTML tags in various controls
<deny users="?" />
<allow users="*" />
<deny users="?" />
<allow users="*" />
<pages validateRequest="false" />
<httpRuntime requestValidationMode="2.0" />
Your installation of Zengagers WebToolz is now complete.
We have created this document as a central reference point for licensees, partners and consultants who use the WebToolz software. It covers processes, information and procedures that relate to licenses, upgrading, support and other useful areas.
Please refer to this document before requesting support for your WebToolz system.
WebToolz Deployment and Maintenance
WebToolz is a module that is deployed on the iMIS staff web site. It needs to be used and updated synchronously with iMIS. It requires files to be copied onto the server in order to function.
If you are considering upgrading your iMIS to either an unreleased version of iMIS or the very latest general release version of iMIS, please do check with Zengagers (firstname.lastname@example.org) regards the functioning of your version in the particular release of iMIS. This site will be updated regularly with the latest release downloads and release notes. You can download the latest version from the Downloadz tab. We will test and release a new version of WebToolz for every GA release of iMIS.
Is WebToolz updated each time ASI updates iMIS?
Not necessarily. There will be occasions when there is a delay between the release of a new version of iMIS and a release of the appropriate version of WebToolz.
If you are wanting to install a new copy of iMIS for a new project then clearly you will want to use the most up-to-date copy of iMIS. Please do not choose the iMIS version without first finding out if there is a version of WebToolz that supports that specific iMIS version. We will either advise you to install a slightly older version of iMIS that can support a release version of WebToolz or we will offer you a “beta” version of WebToolz with the caveat that we make no promises about performance and there may be support limitations.
Choosing the right level of support assistance
When you purchase a license for WebToolz there are a number of options to consider:
Standard Subscription Support
The standard license for WebToolz (any version) includes what we term “subscription support included” (SSI), and is designed to provide a basic level of technical support - what this means is that we will not charge you for telling us about any issues you have with the software, investigating and rectifying software problems that you have and providing general "how to" advice about the product under most circumstances.
- If there is an issue that is caused by an underlying issue that is connected with your iMIS or your specific site infrastructure or configuration.
- If the issue is connected with custom stored procedures, scripts or iMIS or iMIS third party modules such as Task Centre.
- WebToolz relies heavily on the ability to write stored procedures and understand SQL scripting. Support for SQL scripting is specifically excluded from the subscription support included (SSI). We will provide examples for WebToolz controls to give you an idea of how they work, and you are free to use and copy these examples. However, we will not support your writing of the SQL scripts. The SSI support for WebToolz ends at passing the parameters correctly over to the stored procedure, and begins again at the point where the stored procedure is passed back to the WebToolz iPart. The writing, syntax and functioning of the script are outside the domain of regular SSI support.
NOTE - Zengagers are not responsible for the functioning, misfunctioning or data issues caused by the stored procedures. It is the responsibility of the person deploying the stored procedure to check on a test system that it is functioning correctly, before deploying to a live environment. We strongly recommend against writing any stored procedures to the iMIS transaction (Sales Ledger) system as this schema can change upn upgrading iMIS and cause the stored procedures to stop functioning.
The SSI support does not have a priority SLA attached to it. You are welcome to log an issue with us and then follow up on that issue. We will do our best to help you resolve the problem. Please do let us know if you have an important deadline or timescale and we will try to be accommodating.
If a support call is referred to our dev team for processing because we believe that you have found a bug then we will record your original call request in our Trello development database. Where a bug or request is processed by development it is very important that dev fully understand and can see themselves the issue you are reporting. This is so they do not “fix” an issue which is slightly different from that which has been reported. We operate on an “agile” basis in dev so your fix may take a number of weeks to be incorporated in a release and made available as a hot fix.
WebToolz Advanced Support (chargeable)
If your requirement for support is at a higher level because the forms that you want to create are more complex or because you want to do something which may not be obvious or because your iMIS infrastructure is more complex or because of the sheer size of your IMIS installation, then there are other options you should consider. The options that we have available are as follows, and we can provide further information and quotes on each of these on request.
- Prepaid advanced-level support
- Or ad-hoc consultancy
We recognise and fully understand that clients' requirements may vary considerably and often are substantially complicated in nature. There may be some things that you know intuitively software will do and then maybe other things which you think it should do or could do but nobody is quite sure of whether the use of a particular feature on the software is the right way of achieving that end result or whether there may be other ways to achieve the best results within the iMIS family of products. In these cases working with your mentor for a time can be the best approach. With our mentor service we will not actually create and deploy the form system for you, we will advise you or your chosen partner on the best way of achieving the particular goal.
We will work with you until the page is live or until the end of the mentoring or pre-paid support or consultancy period.
the new version of WebToolz 4.4.0 does allow bulk creation of user accounts.