Configuring Taskbuilder

Description: Taskbuilder is a feature in IQ that allows users to create customized "tasks" to facilitate data entry into IQ. For example, an office may use this feature to support their tasks of processing internship applications. These instructions teach users how to configure this feature.

Taskbuilder is a tool designed to help with creating simple user-defined “tasks” for more efficiently entering data into IQ.

You can find the Taskbuilder in the site menu under the Admin section, which will bring you to a list of the currently existing tasks. From there you can either select a task to edit it, or create a new task.

The data in section handles what information should be pre-filled upon entry to the task, and where that information should come from. For instance, a default name value. For most tasks, you won’t need to do much in this section.

The builder handles defining fields that the user of a task sees and can enter data into. A preview of the task is visible on the right-hand side of the builder, and will automatically update as you add, remove, or modify fields.

The data out section defines how data entered into the task should be returned to the server, and where it should go. Here is where you would define, for instance, what properties of a workflow should be filled out by the data the user entered.

Taskbuilder is a variable-driven tool. In order to use it, fields must be given identifying names which will allow you to reference their values. For instance, in the builder section, you could assign a text field an ID like “textValue”. You can then reference this value on the data in or data out sections through that ID.

In order to identify a field by ID on the data in or data out pages, the ID must be written as ${<id>}. For instance, with the “textValue” field mentioned before, you would reference its value as ${textValue}. The reason behind this formatting is so that you can write IDs to create values like this:

In this case, the firstName and lastName IDs could both be used in the resulting value. If, upon submission, the ID firstName had the value “Thomas” and the ID lastname had “Coleman”, the result used in the output of the task would be:

When a $ character is entered into one of the fields that accepts these, the builder will also automatically pop up a list of IDs you have currently already defined in the form.

At the bottom of this list, you will also find certain special values defined with a tilde (~) at the start, such as ${~user} and ${~date.today}. These values are built-in identifiers for certain special values:

~user

The ID of the user filling out the task.

~date.today

The current date. May also take an integer in place of “today”, such as ~date.5, which will fill with that many days after the current date.

e.g. If the date is 5/1/2021, ~date.5 will enter 5/6/2021.

1.Title - Controls the name of the task. The name can be seen at the top of the preview pane.

2.Description - An optional description for the task. This is not displayed to the user on the task itself, but will be shown in the task list page.

3.Service template - An optional selector for a service template to pull field data from. This will allow you to use workflow user-defined fields on the task, corresponding to the associated template selected here. If creating a workflow in the data out section, this field will also control the default template used for the new workflow.

4.Incoming values - This shows a list of the current incoming values, and allows you to add new ones or modify existing ones. More details in the next section.

5.Task preview - A display of the task as it appears in the viewer. Updates upon save. The task can also be viewed in full screen with the “view” option under the actions menu in the top right.

To add a new incoming data source, click the “Add Additional Source” button to add a new row. You may then edit the source by clicking the pencil icon to the right of its row. The following popup will then be displayed:

The source dropdown defines where the data should originate. There are five different options in this field:

1.Direct - A hardcoded value. Use this if you always want a field to default to a specific value.

2.URL Key Remap - By default, values will be automatically pulled from the URL; for instance, if the URL has a “name=Thomas” parameter, the ID “name” will automatically populate with the value “Thomas”. This source will allow you to remap the “name” key to some other ID if desired.

3.Object - Extracts data from an existing object (either a contact, message, or workflow). Which object to use must be identified by either a hardcoded ID for the associated object, or using an ID already set by a different source.

As an example, suppose we want a task to modify existing data in a workflow, and we have the ID for the workflow passed in the task’s URL like so:

As mentioned before, parameters from the URL will automatically enter into the corresponding IDs. With the URL in this case, the “workflow” ID will populate with the value “1234”.

If we wanted to then extract values from this workflow to use in the task, we could do so by filling out an Object source like so:

Note that the ${workflow} field value has been entered into the object ID box, so its value will specify the actual workflow we want to extract data from.

The rows below then map the properties of that workflow (its status and primary person) to IDs in the task (“status” and “person” respectively). Additional data could also be added if desired with the “add additional” button at the bottom.

1.Page - Pages of a task will be shown sequentially each time the “submit” button is pressed at the bottom of the task. The user can not advance to the next page of a task until they successfully submit the current one (i.e. required fields are filled out, etc.). Pages may be rearranged by dragging their tabs.

2.Fieldset - Fieldsets define groupings of fields. Inside the task, only one fieldset will be maximized at a time; minimized fieldsets will display a summary of the information currently entered inside them instead. Advancing to the next fieldset can be done by clicking the “continue” button at its bottom, or by clicking a minimized fieldset to open it.

3.Field - New fields can be added with the types pane to the left. Fields can be rearranged or moved between fieldsets by dragging the arrow icon on the right.

4.Available field types - Select a type here will add that to the task; new pages or fieldsets can also be added here (if none are present when a field is added, a new page and fieldset will be automatically generated). Types can also be dragged from the type list to the task to add them directly at the desired position.

5.Task preview - A display of the task as it appears in the viewer. Updates upon any changes made to the fields. The task can also be viewed in full screen with the “view” option under the actions menu in the top right.

Fields (or pages and fieldsets) may be added via the field type list on the left side of the builder. Among these are the following options:

2.List page - Adds a new list page to the form. List pages function similarly to a dropdown, but in full screen mode.

4.Text block - Adds a non-editable text block to the form. Information, links, and images can be added using this without requiring an actual editable field.

6.Radio buttons - A list of options from which the user can select a single value. All options are displayed on the form at once.

7.Checkboxes - A list of options from which the user can select multiple values.

9.Workflow UDF - Adds a UDF from the service selected on the “data in” section of the task builder. UDF fields will automatically be set up according to their requirements.

10. Contact search - Adds a set of textboxes used to search the database for people. NOTE: If there is a “phonepopup” parameter in the URL, the phone number field of this will automatically populate with that value.

11. Action - Adds a button (or list of buttons) that will perform certain special actions, such as redirecting to another task.

ID - The identifier for the field. This can be set to anything, and is used to reference the value entered into the field.

Label - A short descriptor for the field. On textboxes and dropdowns, this will be displayed in small text at the top of the field. It will also be displayed on a minimized fieldset, as a label for the value currently entered into that field.

Description - A block of text displayed above the field. HTML can be entered into this area.

Placeholder - Gray text to display within the textbox when no value is currently entered into it. Note: for accessibility purposes, you should not place important information in this.

Required checkbox - If checked, the field must have a value for the page to be submitted.

Display only checkbox - If checked, the field will not be editable. Use this if you want to display data from the “data in” section of the task, but not allow the user to actually modify it.

Max characters - The maximum length of the value the user enters into this field.

Format - An optional format to restrict user input to. Numerical characters may be required with a “9”, while alphabetical characters may be required with an “a” (non-alpha-numeric characters will automatically enter as the user types). For example, a phone number may be required with the format (999) 999-9999.

Radio buttons, checkboxes, and dropdowns will also have an additional section for the source of values:

2.Database table (selection) - A defined list of possible values, with values selected from some database table (e.g. affiliation codes, users, etc.),

3.Database table (filtered) - An arbitrary list based on a data table. By default, this will retrieve all possible values from the specified data table; an SQL filter may also be optionally applied to reduce the options further. Note: if the database table supports archiving, archived values are automatically excluded by default.

For example, to allow the user to select from a list of all affiliation codes, you would set the following:

In the case of workflow UDFs, after selecting a UDF, many of the popup’s fields will automatically be filled out according to the UDF’s requirements:

Note the “add to data out” checkbox at the bottom, as well. If the field is saved while this is checked, the value of this field will automatically populate onto the Data Out section of the task builder. In most cases, you will probably want to have this checked to save time later.

The action field type is significantly different from the other field types. When adding one, you’ll be presented with the following:

The action field allows you to add a list of buttons which will perform different actions when clicked. These buttons may be customized with an optional tooltip and color as well. Currently, the actual actions taken may be either redirecting to another task, or redirecting to a URL.

When redirecting to another task, all ID values will be retained (e.g. if the original task had a value under the ID “service”, the same ID will also be filled with that value in the redirected task). The “ID Remap” list will allow you to redirect values of fields if necessary. The “from” box will allow you to pick from IDs present on the current task, and the “to” box will allow you to pick from IDs present on the destination task.

For example, if task A has a field with ID “service” and task B has a field with ID “serviceCode” that you want task A’s service value to transfer into, then you would remap “service” to “serviceCode” here.

Redirecting actions also have an optional “autosubmit” checkbox. In this case, the destination task will attempt to immediately submit the task upon entering it. This may be useful if you have all the necessary information filled out in the first task and are only using the task to send that data to e.g. a particular workflow type. Notably, in doing so you may also want to set the destination task’s “redirect” to return to the original task after a successful submission. See the data out section for details on this.

1.Redirect URL / Task - Optional URL or task ID to redirect to once the task is successfully submitted; if blank, the task will simply refresh itself.

2.Outgoing values - This shows a list of the current incoming values, and allows you to add new ones or modify existing ones. More details in the next section.

3.Task preview - A display of the task as it appears in the viewer. Updates upon save. The task can also be viewed in full screen with the “view” option under the actions menu in the top right.

To add a new outgoing data destination, click the “Add Additional destination” button to add a new row. A workflow destination may also be automatically added from the builder section by checking the “add to data out” checkbox when saving a workflow UDF field.

You may then edit the destination by clicking the pencil icon to the right of its row. The following popup will then be displayed:

The destination field allows you to define what sort of destination should be used. Currently, there are three options:

1.Object - Writes values into an object in the database (either a workflow, contact, or message).

2.URL Key - Appends the value to the task’s redirect URL. For instance, if the task redirects to https://www.google.com, and this destination is set to assign a “num” ID to a “number” key, the resulting url would be https://www.google.com?number=<num>, where <num> is the value entered in to the num field.

When entering an object, you may optionally specify the object ID to write to, in the event that you are updating an object rather than creating a new one. If the object ID is left blank, a new object will be created instead.

You must then specify what fields should be entered into which properties of the object. IDs from the task may be referenced by surrounding the ID like ${<ID>} (see the introduction section for more details on using this format). Additional property rows may be added using the “add additional” button below the property list.

Notably, workflow UDFs fields can also automatically add corresponding property rows if the “add to data out” checkbox is checked when the field is saved.

3.Hover your mouse over the newly created tile and click the gear icon on its top right. If you added a “Task” tile, there will be one dropdown for the task link to display. If you added a “Quick Task” tile, there will be four.