How to Create an Action That Takes Parameters

Monday, July 26, 2010 by Alexander Huber

Last week, a user brought to our attention that there was no example in our help that demonstrated how to implement an action that takes parameters. Therefore, I want to give a quick example of how to achieve the latter behavior. First let me say that the following example is rather trivial, but it should suffice to show you the basic principles of actions.

Let us say that we want to implement an action that changes the user of specific timesheets plus updates the description to leave a hint that the timesheet was updated by an action. The scenario requires four steps:

Creating an action
Creating a parameter entity for the action
Creating an excecution condition for the action
Providing source code that does the actual work

In the following, I describe the above steps in detail.

Creating an action

First we need to create a new action. Therefore, we enter the module Anpassungen and change to the “Server” context. With a right click on Actions we create a new action UpdateTimesheet.On the right pane we can set properties of the action. Under the Parameters section, we can choose between either No parameters required or Use entity as parameter type. As we want to implement an action that takes a parameter, we choose No parameters required. However, up to now, time cockpit only supports TypedParameters. That is, we must create a dedicated entity that we can use as parameter.

creating an action

Creating an action parameter

Now we have an entity that can be used as a parameter for our UpdateTimesheet action. Hence, we can continue editing our action again. For the parameter to be available, we need to reopen the UpdateTimesheet action for editing. We can use UpdateTimesheetParameter as parameter entity for the action now. So each time users choose to execute the action, an auto-generated form for the parameter entity (a parameter dialog) is opened and users can set the values of the relation and property. Besides auto-generated forms, parameters can also have custom defined forms. A description of how to use custom forms will be covered in one of the next blog posts.

Creating an action parameter

Creating an execution condition

As we want our action to only work on timesheets, we need to define a condition under which circumstances an action should work. So we choose the Conditions section and add a new condition TimesheetCondition. Under Entity we choose APP_Timesheet. Now, we have an action that has a parameter and functions only on timesheets. Unfortunately, the action has no source code to execute. So the next step is to implement the IronPython code that does the real work.

Creating an execution condition

Providing source code that does the actual work

The source code that does the trick looks like the following:

clr.AddReference("PresentationFramework") 
clr.AddReference("System") 
from System.Windows import MessageBox 
def actionSample(actionContext): 
  # the input set contains the selected timesheets 
  for item in actionContext.InputSet: 
    item.APP_UserDetail = actionContext.Parameter.NewUser 
    item.APP_Description = actionContext.Parameter.NewDescription 
    actionContext.DataContext.SaveObject(item)

What we do is, we iterate over all timesheets that have been selected by the user and for each timesheet we set the new user and the new description. We can access the parameter by calling actionContext.Parameter. In the context of the UpdateTimesheet action, actionContext.Parameter represents an instance of the UpdateTimesheetParameter. That is, we can call actionContext.Parameter + name of property/relation to get the values of parameter entity.

Setting the source code

Executing the action

After all the latter steps, we now can execute the UpdateTimesheet action on timesheets. For this purpose we select all timesheets that have no user set. We select the timesheets and choose UpdateTimesheet in the Actions menu.

Executing the action

After hitting UpdateTimesheet, users are prompted for a new user and a new description in an auto-generated parameter dialog. This is where users set the parameter values that should be passed to the source code of the action. After saving the parameter, the action is executed and the timesheets are updated accordingly to the new user/description that have been entered in the parameter dialog.

Setting action parameter values