Related Topics
This section documents how to write custom process scripts for Process Director. A process script is called from a Script activity in a Process Timeline definition. The Script task type specifies a Script Function Name. This function name can a custom script function. Your custom functions can be located on a specific custom script file (in the Process Director database). Each step in the process definition points to a script file.
To develop process Scripts inside Visual Studio, use the fully functional Visual Studio project installed with the product named bpVS.zip.
Using a Specific Process Script File
To write a custom script for a process, create a script file with “.ASCX” as the file extension on your local hard drive. Add your custom script code and then upload the file to the Process Director database using the Create New menu item in the Content List (select Document/File in the dropdown). Browse to the location of your ASCX file and upload the file to Process Director. This file will be displayed in the Content List on the server. To make changes to this script file, you must check out the file first, update it, and then upload the new version. For information about modifying files and documents on Process Director, refer to the Implementers Reference Guide. The script for a process is configured in the Properties page of the process definition. The script must exist in the Process Director database and it will be called when a Script task is run in the Process Timeline. For more information on configuring process definition properties refer to the Process Timeline topics in the Implementers Reference Guide.
Writing a Process Script Function
The optional parameters specified in the Script task are used to call your Script function in the process custom script file. For example if you specify “SOME_PARM” as the Script Parameters specified in the Script task, the parameter to your C# function (pParm in the example below) will be set to “SOME_PARM”. If you need to pass multiple values to the process script, you'll need to encode the values by separating them by commas or other techniques (e.g. MY_PARM,1,2). The entire string will be passed to the process script function as a single parameter. You'll need to parse the string into its components using C# string manipulation functions. Your function in the script file would look as follows:
<%@ Control Language="C#" AutoEventWireup="false"
Inherits="BPLogix.WorkflowDirector.SDK.bpFormASCX" %>
<script runat="server">
public override void Process_Script(string pParm)
{
bp.log0("Called Process script:" + pParm);
}
</script>
This function is immediately available to all processes as soon as the file is saved. You may also use System Variables in the Script Step parameter field to extend the capabilities of the process script.
This method will be called with the following environment:
|
LOCAL VARIABLE |
DESCRIPTION |
|---|---|
|
|
The current Workflow object (deprecated) |
|
|
The current WorkflowStep object (deprecated) |
|
|
Optional Form instance object of the process form |
|
|
Instance of the current Partition object |
|
|
Optional instance of the current Project object |
|
|
Optional instance of the current ProjectActivity object |
|
|
The bp environment |
Debugging Process Scripts
To test your custom script, run the process that contains the Script task that calls your function. When that step in the process is run, any error will cause the step to remain running and never complete. View this step using the Timeline/Administration tab of the Timeline instance.
If any errors are encountered running the script, the step will stop with and have the status set to Error. The status field of the step will show the exact error (e.g. a compile error for the script). Correct any errors in your custom script and then right click the Timeline Activity in the Timeline/Administration tab of the Timeline instance, and select Restart Activity. When your script runs successfully the activity will complete and transition to the next step in the process.
You can also debug a process script using the logging functions, like bp.log0 and bp.log1.
Process Script Handlers
This section documents how to write custom script handlers for Process Director which are called prior to each process step starting, when an error is encountered, and when the process step ends. Process Timelines have similar script events that can be incorporated into the process script. You can configure a single script file in the process definition by using the Advanced Options tab of the Settings.
Scripted behavior can be added to the beginning or end of any Process Timeline Activity. The script events Timeline_StartActivity and Timeline_StopActivity events are used for Timelines. The Timeline_StartActivity event is called prior to the start of each Timeline Activity. Similarly, the Timeline_StopActivity event IS called when each Timeline Activity ends.
Using a Specific Process Script File
To write a custom script for a process, create a script file with “.ASCX” as the file extension on your local hard drive. Add your custom script code and then upload the file to the Process Director database using the Create New menu item in the Content List (select Document/File in the dropdown). Browse to the location of your ASCX file and upload the file to Process Director. This file will be displayed in the Content List on the server. To make changes to this script file, you must check out the file first, update it, and then upload the new version. For information about modifying files and documents on Process Director, refer to the Implementers Reference Guide. This script for a process is configured in the Properties page of the process definition. The script must exist in the Process Director database and it will be called when a Script task is run in the process. For more information on configuring process definition properties refer to Workflow and Timeline chapters in the Implementers Reference Guide.
Writing the Script Handler
Your function in the script file would look as follows:
<%@ Control Language="C#" AutoEventWireup="false"
Inherits="BPLogix.WorkflowDirector.SDK.bpFormASCX" %>
<%@ Import Namespace="System.Collections.Generic" %>
<script runat="server">
// these functions are used for Timeline activities
public override void Timeline_Script(string pParm)
{
bp.log0 ("Timeline_Script: " + pParm);
}
public override void Timeline_PreActivity(List<ProcessUser> pUsers)
{
bp.log0 ("Timeline_PreActivity");
}
public override void Timeline_StartActivity()
{
bp.log0 ("Timeline_StartActivity");
}
public override void Timeline_StopActivity()
{
bp.log0 ("Timeline_StopActivity");
}
public override void Timeline_Check()
{
bp.log0 ("Timeline_Check");
}
</script>
These functions are immediately available to all processes as soon as the file is uploaded to the Content List.
Timeline_StartActivity will be called at the beginning of every step in the process, even if the step has no users. It is called before Timeline_PreActivity.
Timeline_PreActivity will be called prior to every step in this process starting. The list of users which will be assigned to the CurrentProjectActivity is passed in the pUsers parameter. You can add to, remove, or replace users in this list. Timeline_PreActivity is only called for user steps.
Timeline_StopActivity is called prior to a step’s completion or termination.
Timeline_Check() enables you to check for advancing and due date/timer processing, and can be useful to implement custom timer processing. These are optional overrides that can be defined in the script associated with the Process Timeline.
When a custom timeline script alters the state of a process, it will be invoked immediately after the script runs, so that changes made to the process state are immediately reflected to the user.
|
PROCESSUSER PROPERTIES |
DESCRIPTION |
|---|---|
|
UID |
The UID of the user who will be assigned to this step |
|
SUID |
Optional STEP USER ID that is starting this user, could be a group step user record |
|
AdminUID |
Optional, used to set the UID of the person adding the user to this step |
|
AdminComment |
Optional, used to set the comment from the person adding the user to this step |
This method will be called with the following environment:
|
LOCAL VARIABLE |
DESCRIPTION |
|---|---|
|
|
The current Workflow object (Deprecated) |
|
|
The current WorkflowStep object (Deprecated) |
|
|
Optional Form instance object of the process form |
|
|
Instance of the current Partition object |
|
|
Optional instance of the current Project object |
|
|
Optional instance of the current ProjectActivity object |
|
|
The bp environment |
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.
