Creating a New Bean-based Task

This topic provides step-by-step instructions on creating a new Bean-based task. You use the Web Customization Editor to create and edit a bean-based task. You create a task using the Task Creation Wizard, and you modify a task using the Task Editor. To use either the wizard or the editor, you must first launch the Web Customization Editor.

The steps below walk you through the process of using both the Task Creation Wizard and Task Editor and provide a brief explanation of the information that is entered in each step.

Using the Task Creation Wizard

1. Select the Application Settings tab and click MicroStrategy Web Configuration to expand the hierarchical tree of customizable features. 

2. Right-click Tasks and select New Task to launch the Task Creation Wizard. 

3. On the first panel in the wizard, click Create a Task using an existing Bean and Event (XML based Bean Task) to specify that you want to create a bean-based task, rather than a Java-based task. Click Next.

4. On the second panel of the wizard, enter the following information: 

   1. In the Task ID field, enter a unique identifier for the task.

      This value will be used both as the internal identifier for the task and the name of the task XML file. Initially, this value will also be used as the name by which the task is registered— that is, the user-facing name which is displayed in the Task  Administrator application. Once you have created this task, you will be given the opportunity to specify a different registered name using the Task Editor. 

   2. If you do not want to use the default base class, enter the fully qualified class name of a different base class in the Fully Qualified Task Class field or click ... to select it.

      By default, beanTask is used as the base class for all bean-based tasks. If you want to use a different base class, you can do so by entering a different class here. Your new base class must extend the com.microstrategy.web.app.tasks.BeanTask class (which in turn extends the Task class).

      You normally specify a different base class if you need to override one or more methods in the default base class. This might occur if the semantics of the XML that defines a bean-based task do not fully convey the nature of your task or if the nature of your task is more dynamic. Specifying a different base class lets you declare some aspects of your task through the XML and implement the rest in Java. 

   3. In the Task Description field, enter a user-friendly description for the task to make it more intuitive and easier to use.

      This description will be displayed on the Home page of the Task  Administrator application. Make this as descriptive as possible to help users understand the full nature of the task. 

   4. In the Bean Name field, enter the name of the web bean associated with the task.

      This is the bean that will do the work for your task. 

   5. In the Bean upon which your task will be based field, enter the type of web bean associated with the task or click ... to select it.

      This is the textual type of the web bean that you specified in the Bean Name field, such as “ReportBean” or “FolderBean”, rather than a numeric code representation. See the EnumSysBeanNames type for a description of all possible values. 

   6. If you want to use a style (and its associated transform) to format the data, select a style from the Style to be used to format the data drop-down menu.

      This is the style that will be used to render the bean's output. 

   7. For Expose style as task parameter, select Yes or No. If you select Yes, make the following additional choices:  

      • If the task parameter is required, select YesforRequired?. 

      • In the Description for style parameter field, enter a description for the parameter.

   8. If you want to use a different base class for the new task you are creating and the base class does not already exist, you can check the Create Java Class check box. When you do this, the Web Customization Editor automatically creates and opens a skeleton Java class when the Task Wizard has finished creating the new task. The new class extends the class you specify below as the Super Class.

5. On the third panel of the wizard, select the event(s) that should be triggered when the task is executed. Click Next.

   For most tasks, a single event handles the data collection needs. If a task requires a sequential application of several events, then several events should be specified. Events will be evaluated in the order they are specified.

   For some tasks, it is possible that the selection of the event itself is not static. In this case, the event must be selected programmatically by the base class (by overriding the prepareEventRequestKeys method). In this case, you do not select any events on this panel. You do have to specify a different base class on the second panel.

6. If you selected at least one event on the previous panel, the next panel of the wizard lets you select event arguments that will be used as task parameters when the task is executed. In the left-hand pane, highlight each event argument that you want to add and use the >> button to select it (that is, to move it to the right-hand pane). To remove a previously selected event argument, highlight it in the left-hand pane and use the << button to deselect it (that is, to move it back to the left-hand pane).  For each event argument that you select, specify the following properties:

   • Exposed?
     To allow the event argument to be overridden for a task invocation, you expose it here by clicking theYesradio button. 

   • Name
     This is the name of the argument used by the event. This value cannot be modified. 

   • Alias
     Enter a value here if you are using a task parameter as the value of the event argument and the names of the task parameter and the event argument are not the same. For example, you might want to do this to make your task’s API more consistent or reduce confusion. 

   • Description
     Enter a user-friendly description for the event argument. This description appears on the Parameters page of the Task  Administrator application. 

   • Required?
     Mark the event argument as required if it is necessary in order for Parameters page of the Task  Administrator application.

     The default value is for a task parameter isnotto be required. When you declare that a parameter is required, it not only helps to describe the parameter, but it can also be used by the Task Infrastructure to validate an incoming request. Bean-based tasks that lack a required parameter are immediately denied. 

   • Default value

     If the event argument  is not required, you can enter a default value that users can accept without doing anything. The default value is used whenever the task user does not provide a value for the event argument, but when the task user does provide a value, it is used in place of the default.

When you have finished adding event arguments and specifying their properties, click Next.

7. If you selected a style from the Style to be used to format the data drop-down menu on the second panel, the next panel of the wizard lets you select the style parameters that will be used as task parameters when the task is executed. In the left-hand pane, highlight each style parameter that you want to add and use the >> button to select it (that is, to move it to the right-hand pane). To remove a previously selected style parameter, highlight it in the left-hand pane and use the << button to deselect it (that is, to move it back to the left-hand pane).  For each style parameter that you select, specify the following properties:

   • Exposed?

     To allow the style parameter to be overridden for a task invocation, you expose it here. 

   • Name

     This is the name of the style parameter used by the event. This value cannot be modified. 

   • Alias

     Enter or modify a value here if you are using a task parameter as the value of the style parameter and the names of the task parameter and the style parameter are not the same. For example, you might want to do this to make your task’s API more consistent or reduce confusion. 

   • Description

     Enter a user-friendly description for the style parameter. This description appears on the Parameters page of the Task  Administrator application. 

   • Required?

     Mark the style parameter as required if it is necessary in order for the task to be executed correctly. This requirement appears on the Parameters page of the Task  Administrator application.

     The default value is for a style parameter not to be required. When you declare that a style parameter is required, it not only helps to describe the parameter, but it can also be used by the Task Infrastructure to validate an incoming request. Bean-based tasks that lack a required parameter are immediately denied. 

   • Default value

     If the style parameter is not required, you can enter a default value that users can accept without doing anything. The default value is used whenever the task user does not provide a value for the style parameter, but when the task user does provide a value, it is used in place of the default.

When you have finished adding and removing style parameters and specifying properties, click Next.

8. The next panel of the wizard provides a table where you can add any additional parameters that will be used when the task is executed. To add a new parameter, click the Add button beneath the table. A check box appears in the Required column  in the table and **ParameterName** appears in the Name column. Specify the properties for the new parameter in the table. The name is the only required attribute. The description, default value, and required attributes are optional.

   • Required

     Mark the parameter as required if it is necessary in order for the task to be executed correctly. This is an optional value. This requirement appears on the Parameters page of the Task  Administrator application. The default value is for a parameter not to be required. When you declare that a parameter is required, it not only helps to describe the parameter, but it can also be used by the Task Infrastructure to validate an incoming request. Bean-based tasks that lack a required parameter are immediately denied.

     When you create a Java-based task, you can control if and when tasks that lack a required parameter are denied. You accomplish this using thecheckForRequiredParametersmethod during request processing.

   • Name

     This is the name is the parameter. This is a required value.  

   • Description

     Enter a user-friendly description for the parameter. This is an optional value. 

   • Default value

     If the parameter is not required, you can enter a default value that users can accept without doing anything. The default value is used whenever the task user does not provide a value for the parameter, but when the task user does provide a value, it is used in place of the default. This is an optional value.

When you have finished making these choices, click Next.

9. If you checked the Create Java Class check box on the second panel, the next panel of the wizard lets you select the source folder for your MicroStrategy project and specify the methods that can be overridden. When you have finished making these choices, click Next. 

10. The final Results panel of the wizard displays the name of the new task that is about to be created and lists all of the parameters that you selected for the task, including the parameter name, whether it is required, and the default value if it exists. If you want to make changes, use the Back button. When you are satisfied, click Finish. 

If you checked the Create Java Class option on the second panel, a Java file for the base class for the new task is launched. Skeleton code is generated using the information you supplied. You must add your own custom code to the Java file to achieve your customization objectives.

Your new bean-based task now appears under the Tasks setting of the Web Customization Editor. It is identified by a blue icon with the text "XML". The corresponding XML file, with the same name as the task ID, is saved under plugins\<currentPlugInName>\WEB-INF\xml\beanTasks in the MicroStrategy Web installation directory.

Using the Task Editor

When you create or select a bean-based task under the Tasks setting of the Web Customization Editor, a tab with the name of the task opens in the right-hand pane of the editor. It has four sub-tabs which allow you to modify the bean-based task.

• Basic Properties 

• Event Parameters 

• Style Parameters 

• Additional Parameters

Three of these tabs contain information about parameters. The interface to your task is through its parameters, including event arguments that are exposed through it. Tools such as the Task  Administrator application can present your task in human-readable form, listing the names of all of the parameters and text for the overall task. By declaring your task properly and fully, you are actually providing documentation for anyone hoping to use it. There is another reason for declaring all of your parameters, which involves reduced coupling between your clients and the implementation. For example, it should be possible to modify a task’s implementation (that is, by using a different event or transform) without modifying the client code which invokes it. If your task clearly declares all of the parameters it uses, those parameters can be mapped to new event arguments, style names, and actual parameter values.

Basic Properties

You can modify some, but not all, of the information is displayed on the Basic Properties tab, with the exception of the ID: 

Properties and Parameters

• ID

  This isthe unique identifier for the task and the name by which it is registered. You can change this value, but not in this text field.

  Originally, this is the value that you supplied for the Task ID when you created the task with the Task Wizard. By default, it is used both as the registered name of the bean-based task and as the name of the XML file that defines the task. If you want to register the task with a different name after it is created, you can right-click the task under the Tasks node under MicroStrategy Web Customization in the left-hand pane of the Web Customization Editor and choose Rename.

• Task Class

  This is the base class for your bean-based task. If you do not want to use the default base class or if you want to use a different base class than the one originally specified, you can do so by entering a different class here. Your new base class must extend thecom.microstrategy.web.app.tasks.BeanTaskclass (which in turn extends theTaskclass).

  You normally specify a different base class if you need to override one or more methods in the default base class. This might occur if the semantics of the XML that defines a bean-based task do not fully convey the nature of your task or if the nature of your task is more dynamic. Specifying a different base class lets you declare some aspects of your task through the XML and implement the rest in Java. 

• Description

  This is the description for the task. It should be as user-friendly as possible 

• Admin Task

  Check this check box if you want the new task you are creating to be available only to users who have the security role of Web Server Administrator (that is, whose role isadmin). 

Event Parameters

The value for an event argument can be static or dynamic. If a value is static, the Task Processor will automatically pass this parameter and its hard-coded value as an event argument when the event is processed. A dynamic value varies from one task invocation to another and is obtained from a task parameter at runtime. In this case, the name of the parameter is assigned to the event argument.

You can modify some of the following information, which is displayed on the Event Parameters tab: 

 Events and event arguments

• Bean Name

  This is the name of the bean that will do the work for your task. 

• Bean Type
  

  This is the textual type of the web bean that you specified in the Bean Name field, such as “ReportBean” or “FolderBean”, rather than a numeric code representation. See theEnumSysBeanNamestype for a description of all possible values. 

• Events

  These are the event(s) that should be triggered when the task is executed.For most tasks, a single event handles the data collection needs. If a task requires a sequential application of several events, then several events should be specified. Events will be evaluated in the order they are specified. 

• Event Arguments

  • Exposed?

    This is where you expose an event argument so that it can be overridden for a task invocation. 

  • Name

    This is the name of an argument used by the event. This value cannot be modified. 

  • Alias

    This is where you can specify a value if you are using a task parameter as the value of the event argument and the names of the task parameter and the event argument are not the same. For example, you might want to do this to make your task’s API more consistent or reduce confusion. 

  • Description

    This is the user-friendly description for the parameter. This description appears on the Parameters page of the Task  Administrator application. 

  • Required?

    This is where you mark the parameter as required if it is necessary in order for the task to be executed correctly. This requirement appears on the Parameters page of the Task  Administrator application.

    The default value is for a parameter not to be required. When you declare that a parameter is required, it not only helps to describe the parameter, but it can also be used by the Task Infrastructure to validate an incoming request. Bean-based tasks that lack a required parameter are immediately denied. 

  • Default value

    If the parameter is not required, this is where you can enter a default value that users can accept without doing anything. The default value is used whenever the task user does not provide a value for the parameter, but when the task user does provide a value, it is used in place of the default. 

Style Parameters

The following information is displayed on the Style Parameters tab:

Style and Style Parameters 

• Style

  The name of the style can be fixed and assigned in the bean-based task XML, or it can be dynamic and supplied through the value of a task parameter. Each style is associated with a particular transform in the Style Catalog Configuration file. When you specify the style to be used with a task, you are indirectly specifying the transform to be used to render the output of the data collected by the task.

  While the selection of a transform is normally done through a declared style in the Style Catalog Configuration file, for a certain class of tasks, no content is necessary. That is most commonly the case in tasks that save information to some persistent data store. Only a success or failure message is required. Since no transform is assigned and no custom content is generated, you do not need to specify a style in this case.

• Exposed as parameter

  This is where you expose the style as a task parameter if you want to allow it to be overridden for a task invocation. 

• Required

  This is where you mark the parameter as required if the style is necessary in order for the task to be executed correctly. The default value is for a style not to be required. When you declare that a parameter is required, it not only helps to describe the parameter, but it can also be used by the Task Infrastructure to validate an incoming request. Bean-based tasks that lack a required parameter are immediately denied. 

• Style Description

  This is where you can enter a description for the style. 

• Style Parameters 

  • Exposed?

    This is where you expose a style parameter so that it can be overridden for a task invocation. 

  • Name

    The value assigned to the style parameter can be static or it can be retrieved dynamically from a task parameter at runtime. If the value of the style parameter is dynamic and varies from one task invocation to another, then the value of the style parameter can come from a task parameter. The value of that task parameter is the value that is assigned to the style parameter. 

  • Alias

    This is where you can specify a value if you are using a task parameter as the value of the style parameter and the names of the task parameter and the style parameter are not the same. 

  • Description

    This is the user-friendly description for the style parameter. 

  • Required?

    This is where you can mark the style parameter as required if it is necessary in order for the task to be executed correctly. 

  • Default value

    If the style parameter is not required, this is where you can enter a default value that users can accept without doing anything. The default value is used whenever the task user does not provide a value for the style parameter, but when the task user does provide a value, it is used in place of the default.

Additional Parameters

On the Additional Parameters tab, there is a table where you can add other parameters that can be passed to the task. Use theAdd andRemove buttons to do this. When yo click theAddbutton, you can enter the following information in the table: 

Additional Parameters

• Required

  This is where you can mark the parameter as required if it is necessary in order for the task to be executed correctly. It is an optional attribute.

  The default value is for a parameter not to be required. When you declare that a parameter is required, it not only helps to describe the parameter, but it can also be used by the Task Infrastructure to validate an incoming request. Bean-based tasks that lack a required parameter are immediately denied. 

  When you create a Java-based task, you can control if and when tasks that lack a required parameter are denied. You accomplish this using thecheckForRequiredParametersmethod during request processing.

• Name

  This is the name of the new parameter. It is a required attribute. 

• Description

  This is the user-friendly description for the parameter. It is an optional attribute. 

• Default value

  If the parameter is not required, this is where you can enter a default value that users can accept without doing anything. It is an optional attribute. The default value is used whenever the task user does not provide a value for the parameter, but when the task user does provide a value, it is used in place of the default.