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
• 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 Collaborator Workbench 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).

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.

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 Collaborator Workbench. 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.

• 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.

• 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 send tasks to users to resolve the exception.

• 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.

Work Step to Launch a Workflow

This work step allows another workflow to be encapsulated within a single step. The two workflows are then linked. When the process flow in the calling workflow reaches this step, the called workflow executes. This only functions synchronously, which means that the two workflows cannot execute simultaneously. The calling workflow waits for the called workflow to complete its work, then resumes execution at the next work step.

The capability to call another workflow adds significant flexibility for designing efficient workflows. For example, let’s say there is a Daily Workflow, and a Weekly Workflow that includes the work of the Daily Workflow plus some extra tasks. The Weekly Workflow can just call the Daily Workflow as one of its work steps. It does not need to redefine those tasks.

Creating a Work Step to Call Another Workflow

1. Double click on “Launch Workflow Step” to bring up the work step dialog.

   

2. In the Step Id text field, enter an appropriate work step name.

3. In the Workflow Schema Group dropdown you may select a group by which the items in the second dropdown are filtered.

4. In the Workflow dropdown, select which workflow shall be called by this work step.

5. In the Recovery dropdown, select what action to take upon recovery if a server crash takes place during this work step.

   

Ask	The engine follows a Fail-To-Execute procedure for the step.
Abort	The engine executes the step again.
Retry	The engine continues with the next step.
Continue	The engine terminates the workflow instance.

Note: For the Launch Workflow Step, the recommended recovery setting is “Ask.”

You may optionally set a pause that will occur between this work step and the beginning of the next one. Select the “Time” tab, then configure the text boxes in the Pause section (Years, Hours, etc.).

Editing Linked Workflows

When two workflow are linked, future modifications can alter both of their behaviors, and this may not be immediately apparent to a user editing the workflow without being alerted to this fact. So when a user clicks on ‘Edit’ for a workflow that is linked to another workflow (it either calls another workflow, or is called by another workflow), the system displays a warning message that identifies the name(s) of the linked workflow(s).

Note that only workflows that are directly linked are named. So if the calling scenario is: wf A > wf B > wf C, when a user starts to edit workflow A, the warning message will provide the name of workflow B, but not workflow C, because it is not directly linked to workflow A.

Note: If a linked workflow is deleted, then the other workflows that were linked to it become invalid. They must now be modified so that they no longer make calls to it or expect to be called by it.

Workflow Recovery

When a server that is running linked workflows crashes, then on recovery, the outer workflow (the calling workflow) is restarted from the current step. For example, if it was at work step C when the crash occurred, then upon recovery execution would begin again at work step C, not work step A.

An inner workflows (a called workflow) however, is simply terminated and must start from the beginning again. So if the outer workflow was at step C, and step C was a call to an inner workflow, and the inner workflow was in the middle of its execution during the crash, then upon server recovery, the inner workflow would always be terminated and the outer workflow would recover step C again per its recovery setting

Since the inner workflow is always terminated upon recovery (if running at the time of the crash), this recovery situation allows the possibility for an inner workflow to be re-run on an unknown state of data caused by the previous run of the inner workflow. In order to mitigate this situation, the user may want to set the recovery setting of the calling workstep of the outer workflow be set to a value of: ‘Ask.’ On recovery, before calling the inner workflow the system will display a dialog asking the user to choose whether to Retry, Continue, or Abort calling the inner workflow. This provides an opportunity for the user to validate the state of the data caused by the incomplete run of the inner workflow and take any necessary steps before re-running the inner workflow

Workflow Recursion

The ability to launch another workflow from a workflow step may lead to a condition that causes recursion among the workflows. For example: Two workflows can call each other recursively. For example: workflow A calls workflow B, and workflow B calls workflow A.

Since, this could potentially lead to an infinite loop, there is a new system parameter that controls the upper limit of the number of recursive calls that the workflow engine will allow. The parameter is described as follows:

PNAME	PTYPE	VALUE_NUMBER	DEFAULT_NUMBER	DESCRIPTION
workflow.recursive.limit	0	2	2	Controls the upper limit on the number of recursive calls during run-time of a workflow. Upon reaching this upper limit, the system will not initiate any more workflows instances that are part of the recursive call. The user who initiated the workflow will be sent a relevant message to the “My Task” pane.

Caution: It is generally recommended not to configure recursive workflows as it results in constant running of the workflows. Recursive workflows should therefore be configured and used only if the business need warrants it.

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

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.