Methods and Workflow

This chapter describes options that you can use to create automated actions in your application, outlines the primary configuration options, and summarizes the available tools.

This chapter covers the following topics:

• Introduction
• Overview of Method Types
• Overview of Workflow Step Types
• Typical Step Properties
• Passing Arguments to a Method
• Workflow Schema Examples
• Workflow Recovery
• Configuration Notes

Introduction

Demantra provides two closely related options that you can use to create automated actions in your application:

• A method is an object-specific action, which the user sees as an ordinary right-click menu option in a worksheet. With the method, the user can view or edit attributes of a level member and automatically launch any processing steps that you create. In Demantra, methods are typically used for any of the following purposes:

  • Viewing, editing, copying, pasting, or deleting level members.

  • Running the Promotion Optimization engine, from a selected promotion.

  • Performing custom processing as needed by the DSM product (for example, matching a settlement to a promotion).

• A workflow is an automated or semi-automated software process. In Demantra, a workflow can perform any kind of processing needed in a Demantra application. These are typically used for any of the following purposes:

  • To automate routine work such as loading data, running the Business Logic Engine, and maintaining the Demantra database.

  • To define activities that require organized participation from multiple users. Multiple users can participate in an automated workflow, receiving tasks at the appropriate times and sending tasks to others as needed.

These two options are closely related because most methods actually include a workflow.

Methods

Each method is associated with a specific level. Also, a method can be available in all worksheets or in a single specific worksheet.

Demantra provides a set of default methods that you can redefine or disable as needed. When you create a level, Demantra automatically creates the following default methods for it:

• New level_name

• Edit level_name

• View level_name

• Delete level_name

• Copy (only for promotional levels)

• Paste (only for promotional levels)

• Paste from Clipboard (only for promotional levels)

You can customize, disable, or delete these methods. You can add other methods as needed.

Method Security

Within the Demantra Local Application Administrator, you can specify user access to all methods (as well as to all menu bar items). See “Specifying Permissions for Menu Items”.

Workflows

In Demantra, a workflow is a logically connected set of steps. Each step can be automated or can require interaction from one or more users or groups. Demantra provides a set of workflow steps, each with predefined behavior.

A workflow is associated with one component, the component to which its creator belongs. A workflow can include any users of the component, as well as any groups (groups can be defined across multiple components).

Caution: Access to the Workflow Manager, including the ability to add and edit a workflow, should only be provided to key users. Workflows are used to drive many administrative flows and critical behind-the-scene processes, including data loading, purging, and execution of the analytical engine.

Overview of Method Types

To execute a method, the user right-clicks a level member in a worksheet (or in a Members Browser content pane) and then selects the method name from the menu. The behavior after that depends on the type of method.

Method Types

Demantra provides the following method types:

Constructor	Prompts the user for values of the attributes of the new member and then adds the member in the database.
Destructor	Removes the member from the database.
Edit	Prompts the user for new values of the attributes for this member and then saves the changes.
View	Displays the values of the attributes for this member.
Custom	Optionally prompts the user for new values of the attributes for this member and then runs a workflow.
Open	Opens the default worksheet, filtered to the selected member. You specify a default worksheet when defining the method.
Open With	Similar to Open, but enables the user to select from a list of available worksheets.
Copy	Copies the selected member to the clipboard. Valid only for promotional levels.
Paste	Pastes the member that was last copied to the clipboard. Before pasting, the user can modify the dates of the promotion or choose to derive them from the worksheet. This option is valid only for promotional levels.
Paste From Clipboard	Enables the user to specify which member to paste from the clipboard. Before pasting, the user can modify the dates of the promotion or choose to derive them from the worksheet. This option is valid only for promotional levels.
Add Note	Add a comment or additional information about the selected member.

Constructor, Destructor, and Edit type methods can also run workflows. The workflow is run after the level member is created, removed, or edited.

Constructor, Edit, and Custom Methods

If the method type is Constructor, Edit, or Custom, the following occurs:

1. Depending on how the method is configured, Demantra may save the worksheet data immediately.

2. Demantra optionally displays a dialog box that prompts the user for values of attributes for this level member, as follows:

   

   For a Custom type method, this dialog box includes an additional check box at the bottom. With this, the user can specify whether to save the attribute changes to the database.

   You can customize the following:

   • Text at the top of the dialog box

   • Attributes to list and the order in which to show them. The possible attributes include Name, each parent of this level, and any additional attributes. You can specify which attributes are required and which are editable. Required attributes are shown in red.

   • Label on the OK button (“Create” in this example).

3. Demantra creates or edits the member as indicated, and saves the changes to the database.

4. If the method includes a workflow schema, Demantra continues as follows:

   1. Demantra constructs the set of arguments to pass to the workflow in memory. Specifically, it constructs an array that consists of the following:

   2. Name-value pairs of the attributes of the member, using the values that the user provided.

      Note: Demantra does not necessarily pass all the attribute values to the method itself. For a custom method, you specify which attributes should be passed to the workflow.

   3. Additional name-value pairs that describe the context in which the method was invoked; see “Passing Arguments to a Method”.

   4. Demantra runs the associated workflow.

      Within the Business Modeler, the method configuration may include additional parameters that control how the method behaves. See “Passing Arguments to a Method”. If any of these parameters have the same name as the arguments that are passed to the method, the values that are passed in memory take precedence over the values in the method definition.

      For example, suppose the configuration for a given method includes a parameter called unit_cost and specifies the value for this parameter as 3.00. If the user invokes this method and specifies unit_cost as 3.50, then the value of 3.50 is saved in the database and is used in the method execution. On the other hand, if the user does not specify a value for unit_cost, the value of 3.00 is used in the method execution.

5. Demantra optionally displays an output dialog box. The output dialog box is similar to the input dialog box, except that the attributes are not editable.

View Methods

If the method type is View, Oracle Demantra does the following:

1. Oracle Demantra displays a dialog box that displays the values of attributes for this level member. This dialog box is a read-only version of the one shown in “Constructor, Edit, and Custom Methods”.

2. When the user clicks OK, Oracle Demantra closes the dialog box.

Destructor Methods

If the method type is Destructor, Oracle Demantra does the following:

1. If the method includes an associated workflow, Oracle Demantra invokes that workflow.

2. It displays the standard deletion confirmation dialog box.

3. When the user clicks OK, Oracle Demantra closes the dialog box and removes the member from the database.

Overview of Workflow Step Types

When you create or edit a workflow schema, the Workflow Manager displays a list of the available kinds of steps:

This section provides a brief overview of all the kinds of available steps, grouped into rough categories. Some kinds of steps fall into multiple categories.

Synchronous and Asynchronous Workflows

By default, Demantra workflows operate synchronously – that is, they wait for one step to complete before proceeding to the next step in the workflow. Synchronous communication works well for most types of Demantra workflow steps, although there are some cases where Asynchronous workflows are better suited. In asynchronous mode, workflow steps are not required to wait for the previous step to complete before executing. For example, workflow steps that notify users are best run asynchronously, so that workflows do not remain idle while waiting for user input.

Asynchronous support is provided for the following types of workflow steps:

• Launch Workflow Step

• User Step

• Group Step

• Exception Step

For more information on how these workflow steps operate in asynchronous mode, see “Workflow Steps”.

Responding to External Events

A common use of workflows is to wait for specific conditions or external events and then launch actions. For example, a workflow could wait for a file to be updated and then import data into Demantra.

The primary tool here is the Wait Until Step, which pauses the workflow until a specific condition is met, possibly from a set of allowed conditions. When the condition is true, the Workflow Engine continues with the next step in the workflow. In this step, the Workflow Engine can look for a specific file and wait until the file is created, or is modified, or reaches a certain size. Or the Workflow Engine can execute an SQL query repeatedly until it returns a new value (for example, when a price changes). You control the frequency of testing, as well as the time-out period and other timing properties.

The Workflow Engine can also respond to user interaction. Several steps (User Step, Group Step, and Exception Step) send tasks to users and then wait until those users either mark the tasks as done or until the task times out. If the task times out, the workflow can continue with an alternative step.

Finally, the Workflow Manager itself can be used to schedule workflows.

Sending Tasks and Email

Some steps send tasks to users or groups; these tasks appear in the My Tasks module for those users, within Demantra Local Application. A typical task is a request to examine a worksheet, make a decision, and possibly edit data. A task can also include a link to a Web page for more information. A task can be accompanied by email. Also, a workflow step can simply send email.

The following kinds of workflow steps support tasks and email:

• User Step sends tasks to a specific user, to ask the user to review and update a worksheet, or to prompt for a workflow decision. In synchronous mode, the User Step sends a task to the specified user or user group, and then waits for the users to make a workflow decision. In asynchronous mode, the User Step sends tasks to the specified user or user group, and then completes immediately without waiting for the user to mark the task as done.

• Group Step sends tasks to a group of users using just one step instead of sending the task individually to each one. This allows you to coordinate your workflow processes with responses from whole groups of users. In synchronous mode, the Group Step sends a task to the specified users/user groups and then waits for the users to mark the tasks as done before proceeding to the next step. In asynchronous mode, the Group Step sends tasks to the specified users/user groups and then completes without waiting for the users to mark the task as done.

• Email Step sends an email to a user that will arrive in the user's standard email application. This step allows integration with the organizational messaging system.

• Exception Step runs a worksheet on which an exception has been defined. If the worksheet returns data, the step then sends tasks to users to resolve the exception.

• Selection Step provides a user with a selection of choices to direct the continuation of the workflow instance. For instance, selection step can be used to obtain approval, rejection, or postponement of workflow activities, or selection of a priority from a list of activities.

Integration

The Transfer Step initiates transfer procedures for the import and export of data. This kind of step is associated with an integration interface, as defined within the Business Modeler.

Managing Demantra Objects

The following workflow steps should be used only as methods. Each of them uses arguments that are available when a user launches a method from a level member or a Members Browser:

• Create Member Step creates the specified level member.

• Edit Member Step makes changes to the specified level member.

• Delete Member Step creates the specified level member.

Other Demantra Actions

The following specialized workflow steps perform actions that are specific to Demantra needs:

• Stored Procedure Step runs a stored database procedure on the database that holds the Demantra data. Demantra provides a set of predefined database procedures, some of which must run regularly in any Demantra solution. See “Database Procedures”.

• BLE Step runs the Business Logic Engine directly on a worksheet to evaluate all the client expressions, split the resulting data to the lowest level, and save it to the database. This step automatically starts the Business Logic Engine if necessary.

• Simulation Step runs simulations and then either automatically accepts the results or displays the results in a worksheet for review by a user.

• Worksheet Cache Step refreshes the caches for specified worksheets, for some or all users.

• Refresh Population Step refreshes the population of a promotion to ensure that the promotion data is aligned correctly when items or locations grouped in a promotion (and defined at the aggregate item or location level) change. For example, items can be grouped under a promotion group. If a promotion is defined for a given promotion group and an item grouped under this promotion group is moved to a different promotion group, then running the Refresh Population Step ensures that the promotion data for this promotion is realigned according to the current promotion group definition.

Logic

The following kinds of steps support programming logic within the workflow:

• Selection Step, which was introduced previously, provides a user with a selection of choices to direct the continuation of the workflow instance.

• Condition Step directs the course of the workflow instance depending on condition results obtained from worksheets run on the Demantra database. Instead of testing a worksheet, you can test an SQL query or a custom Java class.

• Exception Step runs a worksheet on which an exception has been defined. If the worksheet returns data, the step then sends tasks to users to resolve the exception. In synchronous mode, the Exception Step executes the worksheet specified by the user, calculates the exceptions, sends a task to the specified user ( or users) and when the user marks the task as done, the workflow continues to the next workflow step in the workflow definition. In asynchronous mode, the Exception Step performs all of the steps as above and sends tasks to the user, but does not wait for the user to mark the task as done. Instead, it will send a task to the user(s) and continue to the next workflow step in the workflow definition.

• Container Step runs multiple steps in parallel and then proceeds when all are completed.

• Wait Until Step waits until a specific condition is met before allowing the workflow to continue. The condition can be the existence or modification of a given file, or a change in a value in the database.

External Functions

Finally, other kinds of steps call external functions:

• Executable Step runs executables such as Demantra executables (for example, the Analytical Engine), or external executable and batch files. This step allows interaction between Demantra and external software.

• Custom Step runs a Java class and is typically used to define custom methods. If a workflow is configured as a method, then a user can launch it from within a worksheet. In that case, Demantra automatically passes arguments to the workflow, which Custom Step can use.

Typical Step Properties

This section provides an overview of the properties of a typical step.

Connection Handles

Each step has connection handles that you use to connect it to other steps.

Common Properties

When you add a step to a workflow, the Workflow Editor displays a popup page where you can specify properties for that step. Common properties include the following; not all steps have all these properties.

• The User and Group properties specify users and groups, respectively, associated with the step. Generally, the Workflow Engine sends tasks to these users or groups. Some kinds of steps have both these properties, some have only the User property, and some have neither. In some cases, you can specify only a single user, while in other cases, multiple users are permitted.

• The Worksheet Name property specifies an associated worksheet, from the set defined within Demantra. Different kinds of steps use worksheets in different ways. For example, BLE Step evaluates the client expressions in the worksheet.

• Several properties specify built-in processing delays with short default values. For example, the Pause property specifies how long the Workflow Engine should wait after the step is completed, before starting the next step. In this way, you can coordinate workflow activities by making the engine wait for defined periods of time.

• The Timeout>Timer property specifies when the step times out. For example, if the user does not mark a task as done before its due date, then the task will expire or time out. You use this property to prevent a step from stalling the workflow. If you specify a timeout period, you also specify an alternative following step that the Workflow Engine should execute.

  Note: When a step times out, the Workflow Engine executes the timeout step immediately without waiting for the pause counter to finish.

• The Timeout>Alert Time property specifies when the step enters its alert phase.

• The Recovery property specifies the recovery action for the Workflow Engine to use if the system crashes while performing this step.

Passing Arguments to a Method

Demantra can pass arguments in memory to the method. Considered as a group, these arguments are the context dictionary. For each argument, Demantra passes a variable name and its associated value.

Available Arguments

The available arguments fall into three general categories:

• System information, for example, the ID of the worksheet from which the method was launched.

• Member information, that is, information that indicates the member from which the method was launched.

• User inputs, that is, all arguments shown on the Input dialog box. These arguments are generally attributes of the member from which the method was launched.

The following table lists the possible variables.

Category	Variable*	Value	Data Type
System	ws_id	Identifier of the worksheet from which the method was launched.	Java.util.String
System	worksheet_filter	The filter population of the worksheet from which the method was launched. Represented as a list of pairs of level_id and member_id.	java.util.String level_id,member_id; pairs separated by comas and semicolons.
System	view_name	The name of the active view from which the method was called.	java.util.String
Member	level_id	Identifier of the level from which the method was launched.	java.util.String
Member	member_id	Identifier of the member from which the method was launched.	java.util.String
Member	Combination_path	The context of the selected member for the method. Will be represented as a list of pairs of level_id and member_id.	java.util.String level_id,member_id
Member	population.filters (example)	Applies only to promotion levels. The population attribute of the selected member. The name of this variable is based on the name of the population attribute as follows: population_attribute_name.filters	Array of com.demantra.applicationServer.metaDataObjects.level.levelFilters.LevelFilterGetters
Member	population.from_date (example)	Applies only to promotion levels. The from_date attribute of the selected member. The name of this variable is based on the name of the population attribute as follows: population_attribute_name.from_date	java.util.Date
Member	population.to_date (example)	Applies only to promotion levels. The to_date attribute of the selected member. The name of this variable is based on the name of the population attribute as follows: population_attribute_name.to_date	java.util.Date
Inputs	Attribute_column_name	Values of the attributes of the selected member that are specified as inputs to the method (all attributes on the Select Input Arguments screen). The name of each variable is the same as the name of the column in which the attribute is stored.	java.util.Object

Passing Arguments

In order to pass arguments to the method, you must explicitly configure the variables that each workflow step should receive. To do so, you type the parameter names on the Parameters list for that step; see “Properties Used as Arguments for a Method”.

Note: The parameter names are case-sensitive.

For the input variables, you also specify which variables to pass when you configure the method. Specifically you select the desired attributes on the Select Input Arguments screen.

Properties Used as Arguments for a Method

When you configure a workflow as a method, Demantra can pass arguments in memory to the method. Considered as a group, these arguments are the context dictionary. For each argument, Demantra passes a variable name and its associated value.

In order to make these arguments available to a workflow step, you must explicitly configure the variables that each workflow step should receive. To do so, you type each variable name in the Name column of the Parameters list for that step, as follows:

In this example, the first two arguments are standard member variables, from the table in “Available Arguments”. These arguments can be used in any method.

The remaining three arguments are input variables; these variables refer to attributes of the member. Specifically these are the names of the columns in which these attributes are stored (Product Family, Brand, and Name).

Note: In the Parameters list:

• The parameter names are case-sensitive.

• The descriptions are not used by the method.

• If a value is null in this table, then the value is taken from the member from which the method was launched. If the value is not null, then it is used instead of the value taken from that member.

Workflow Schema Examples

Workflows are very often used to import data. In the process of importing data, it is often necessary to perform various kinds of integrity checking and data cleanup, which you do within database procedures. As a consequence, many workflow schemas include the Stored Procedure Step in addition to the Transfer Step.

Example 1

Example 2

Example 3

Workflow Recovery

There may be an occasion when a workflow fails and requires recovery. The primary reasons for this happening are:

• A failure within the specific workflow step, or

• A failure with the Application Server (for example, becoming unresponsive).

Failure in a specific workflow step is typically resolved by correcting an underlying issue with the step itself. A failure by the Application Server can result from a variety of sources that are outside of Demantra's control. When the application server fails and is restarted any workflows which have not completed can be restarted. The Recovery setting of the workflow step that was executing when the application server failed determines the action taken as follows:

• Ask - The engine follows a Fail-To-Execute procedure for the step which sends the workflow owner a notification of failure and asks what should be done next.

• Abort - The engine terminates the workflow instance.

• Retry - The engine executes the step again.

• Step - The engine restarts the the step specified in the drop-down list box..

Specifying the Workflow Step from which you want to Recover

You can specify a recovery step that the workflow will try to execute if the current step fails. If no Recovery Step is specified then the workflow will retry to execute the current step.

1. From the Workflow Editor, open a workflow.

2. For each workflow step for which you want to set a recovery step:

   • Open the workflow step.

   • From the Recovery drop-down list box choose Restart at Recovery Step.

   • From the Recovery Step drop-down list box, choose the step where you want to restart if this step fails.

Skipping a Workflow Step During Recovery

When a workflow is run in recovery mode it may make sense to skip one or more of the remaining workflow steps. This may be due to time constraints for long running processes which are not critical or the fact that precursor steps needed for this step to be valid did not complete. Each workflow step has a Skip During Recovery check box. Enable this check box to have the workflow skip the current step during recovery.

Configuration Notes

This section contains configuration notes related to methods, workflows, and automation in general

Dependencies

Before you can configure a workflow, you may need to define the following elements that it might use:

• Stored procedures

• Java classes

• Batch scripts

• Worksheets

Before you create a method, you may need to define the following elements that it might use:

• Worksheets

• Workflows

Design Considerations

Before you begin creating a workflow schema, you should have a clear idea of the intended purpose, flow, and users of the schema. Also, you should consider the following issues:

• Remember that client expressions that are affected by data changes should not be used until the Business Logic Engine evaluates them. The Workflow Manager does provide a kind of step that submits worksheets to the Business Logic Engine.

• A worksheet must be public in order to be visible from a task. Also, users must have the correct security privileges to view worksheet results.

• Initiators of a workflow instance must have permissions to view worksheet results for all worksheets that the workflow schema includes. If the workflow instance is to be initiated by more than one user, the worksheet must be a public worksheet, and the users of the group must have permissions to view the worksheet results.

• Properties of workflow steps cannot be changed within or by the workflow instance. If you make changes to a workflow schema, those changes do not affect any instances that are currently running.

• Only the owner of a workflow schema can edit that schema. Anyone with login access to the Workflow Manager can launch it.

Tools

Demantra provides the following tools for creating and configuring methods and workflows:

Tool	Purpose/Notes
Configure > Method option in the Business Modeler	Defines methods.
Workflow Manager	Defines workflows.