Related Topics
Custom Tasks can be written in Process Director and used by Forms and Process Timeline definitions. A Custom Task enables common business logic to be packaged in a reusable way and made available to users that are building Forms and Process Timelines. You should be familiar with writing custom scripts for Forms and Process Timelines before writing a Custom Task. There are two types of Custom Tasks; Form Custom Tasks and Process Custom Tasks.
What Custom Tasks Can Be Used For
Custom Tasks can provide various types of business functions that are unique to your environment, or common functions that can be used across multiple Form and Process Timeline definitions. For sample Custom Tasks contact BP Logix.
Form Custom Tasks
A Form Custom Task provides users that are building Forms the ability to execute custom business logic when the end-user is filling out the Form. A Custom Task is mapped to an event on the Form (e.g., a button). When the end-user triggers this event, the Form Custom Task script will be executed. A Form Custom Task can provide a mapping of external fields (e.g. database) to the fields on a Form.
When the script for a Form Custom Task is run, it can optionally display an interface to the user. The Custom Task script can query and/or set any of the form data on the container Form.
Process Custom Tasks
A Process Custom Task provides users that are building processes the ability to use custom business logic in the Process Timeline definition. The Custom Tasks will display a Form interface to the user building the Process Timeline that enables them to configure the data required for the Custom Task. This configuration form is available from the Custom Task tab of a Process Timeline activity of the Custom Task Activity Type. This configuration data will be available to the Custom Task script when the Timeline Activity is run. The Custom Task script will run in a similar environment to a Timeline script and has access to all Timeline objects and their data.
A Process Custom Task can't display an interface to the end-user participating in the process. The only interface displayed is during the configuration of the Custom Task in the Process Timeline definition.
How Custom Tasks Work
Custom Tasks in Process Director provide a way to package reusable functions for Form builders and process implementers. They consist of a Form and a script file. This enables your business logic to be placed in the script, and the Form is used to collect configuration information for the script, and optionally can display an interface (Form Custom Tasks only). a Form Custom Task can be mapped to different events (e.g. form display, button, etc.) on a standard Form and are run when the event occurs.
Configuration vs. Running
The Custom Tasks are executed in the following modes:
ConfigurationThis is when the user is configuring the data needed for the Custom Task to run. During the configuration, it is common to display a list of the form fields in the container Form. This enables fields to be mapped to external sources by the builder of a Form, without requiring them to have any special naming convention for their form fields.
Run-time (run)The Custom Task is run when a mapped Form event is triggered or when aCustom Task Timeline Activity has been invoked. When a Custom Task is run, it has access to the configuration data and the container Form.
Configuration Data
When a Custom Task is configured, a form data instance is created that contains the configuration data entered. This form instance is stored “under” the Form definition or Process Timeline definition, depending on the type of Custom Task. When the Custom Task is run (whether in a Form or Process Timeline), it has access to all this configuration data in this form instance.
Container Form
A Custom Task can have a “container Form”. This is the standard Form that is displayed to the user. a Form Custom Task is mapped to an event on the container Form. A container Form is optional for a Process Custom Task, but can be specified as part of the step configuration on the Custom Task tab of the Timeline Activity's definition. The Form and script part of a Custom Tasks has access to the container form data.
Creating a Custom Task
A Custom Task requires a Form created in the .NET environment similar to how a Form is created. To create a Form for a Custom Task, use the Create New menu item in the Content List and select Form Definition in the dropdown. Then select from the template dropdown “Use Empty .ASCX form”. The Form must be created using the special options in the Form Definition page that is displayed. A Custom Task can be created as a Form-only Custom Task, a process-only Custom Task, or a Custom Task that can be used by both Forms and processes. This Form will also display any Custom Task configuration.
These events are called for forms and while configuring a Custom Task:
public override void BP_Init()
public override void BP_Event(bp.EventType pEventType, string pEventName)
public override void BP_Validation()
public override void BP_Display()
public override void BP_Completed()
When a Custom Task is mapped to a Form, the following Custom Task function will be called:
protected override bool CT_RunTask(bp.FormCTMappedTo pMappedTo, string pEventName)
This event is called to "run" a Custom Task. It should return "true" to show the Custom Task GUI, or false to continue processing the form.
public override bool CT_RunTask(bp.FormCTMappedTo pMappedTo, string pEventName)
This function should return "true" to show the Custom Task GUI.
This is created like any other Custom Task (Form, Process), and when the rule is evaluated that uses the CT, this event will be called:
public override DataItem CT_RunRuleTask()
This is so the Custom Task can return a string, a list of UIDs, etc.
These events are called for Custom Tasks while running a GUI:
public override void CT_Init()
public override void CT_Event(bp.EventType pEventType, string pEventName)
public override bool CT_Validation()
public override void CT_Display()
public override void CT_Completed()
Use this.FormInfo to access the current Form info. For example:
this.FormInfo.FormControl("SomeTextControl").Text = "This is new text";
While in a Custom Task run or GUI, use this.ContainerFormInfo to access the containers form info (get/set form fields, etc). For example:
this.ContainerFormInfo.FormControl("SomeContainerControl").Required = true;
Use this.FormInfo.AddInfoMessage and this.FormInfo.AddErrorMessage to add error or info messages to forms (e.g., for validation). For example:
this.FormInfo.AddInfoMessage(new FormMessageString("This info message
will display on the form!"));
A Custom Task may have 2 sections, FormControlCustomTaskConfig and FormControlCustomTaskRun. For example:
<bpx:FormControlCustomTaskConfig runat="server">
<!--This section includes stuff that is shown when a Custom Task is
being configured-->
<asp:TextBox ID="config_text1" runat="server"></asp:TextBox>
</bpx:FormControlCustomTaskConfig>
<bpx:FormControlCustomTaskRun runat="server">
<!--This section includes stuff that is shown when a Custom Task is
run inside a Form (if CT_RunTask returns true).-->
<asp:TextBox ID="run_text1" runat="server"></asp:TextBox>
</bpx:FormControlCustomTaskRun>
Web Service Custom Tasks
Some of the Custom Tasks can utilize Web Services (e.g. calling a remote Web Service to look up employee information from an employee ID stored on a form). Only certain types of Web Services are directly supported. These Web Services must use primitive data types such as numbers and strings as parameters. Other, more complex Web Services, can be supported by "wrapping" them in a proxy Web Service. This proxy Web Service calls the actual web service, but exposes it using primitive data types that the Custom Tasks support.
An example of a Web Service wrapper is installed in the "C:\Program Files\BP Logix\Process Director" folder as bpProxy.zip. This file contains a complete Visual Studio project creating both a .ASMX Web Service, and a .DLL that has the web reference to the complex Web Service. This Web Service wrapper can be deployed on any IIS server. It can also easily be deployed in the Process Director web site by copying the .DLL to the "C:\Program Files\BP Logix\Process Director\website\bin" folder, and the .ASMX to the "C:\Program Files\BP Logix\Process Director\website\custom\services" folder. After they are deployed, then can be reference like any other web service.
For more information, refer to the Web Services topic.
Documentation Feedback and Questions
If you notice some way that this document can be improved, we're happy to hear your suggestions. Similarly, if you can't find an answer you're looking for, ask it via feedback. Simply click on the button below to provide us with your feedback or ask a question. Please remember, though, that not every issue can be addressed through documentation. So, if you have a specific technical issue with Process Director, please open a support ticket.
