Microsoft Dynamics AX 2012 includes numerous batch jobs that perform operations such as generating reports, creating sales invoices, and processing journals. However, in several situations, organizations need to create their own batch jobs. The batch framework provides full flexibility in the types of jobs that you can create. This section walks you through the following steps, which are required for creating, executing, and managing a batch job:
1. Create a batch-executable class.
2. Create a batch job and define the execution schedule.
3. Configure a batch server and create a batch group. (It be will explained in another post)
4. Manage the batch job. (It will be explained in another post)
Create a batch-executable class
The first step in developing a batch job is to define a class that can be executed as a batch task. Many classes included with Microsoft Dynamics AX 2012 are already enabled for batch processing. You can also design a batch-executable class, as shown in the following example:
public class ExampleBatchTask extends RunBaseBatch
To run as a batch task, a class must implement the Batchable interface. The best way to implement the interface contract is to extend the RunBaseBatch abstract class, which provides much of the necessary
infrastructure for creating a batch-executable class. An alternative is to use the SysOperation framework, which provides additional advantages compared to extending the RunBaseBatch class. Will post more information about the SysOperation framework Later.
Table below describes the methods that must be implemented when you extend the RunBaseBatch class. The following sections describe these methods in more detail.
run methodYou implement the core logic of your batch class in the run method. The run method is called by the batch framework for executing the task defined within it. You can run most of the X++ code in this method; however, there are some limitations on the operations that you can implement. For example, you can’t call any client logic or dialog boxes. However, you can still use the Infolog class. All Infolog and exception messages are captured when the batch class executes, and they are stored in the batch table. You can view these later in the Batch Job form or the Batch Job History form, both of which are located under System Administration > Inquiries > Batch Jobs.
Note If an error message is written to the Infolog, it does not mean that the task has failed; instead, an exception must be thrown to indicate the failure
pack and unpack methods
A class that extends RunBaseBatch must also implement the pack and unpack methods to enable the class to be serialized. When a batch task is created, its member variables are serialized by using the pack method and stored in the batch table. Later, when the batch server picks up the task for execution, it deserializes class member variables by using the unpack method. So it’s important to provide a correct list of the variables that are necessary for class execution. If any member variable isn’t packable, then the class can’t be serialized and deserialized to the same state.
The following example shows the implementation of the pack and unpack methods:
public container pack()
{
return [#CurrentVersion,#CurrentList];
}
public boolean unpack(container _packedClass)
{
Version version = RunBase::getVersion(_packedClass);
switch (version)
{
case #CurrentVersion:
[version,#CurrentList] = _packedClass;
break;
default:
return false;
}
return true;
}
The #CurrentList and #CurrentVersion macros that are referenced in the preceding code must be defined in the class declaration. Using a macro simplifies the management of variables in the class. If you add or remove variables later, you can manage the list by modifying the macro. The #CurrentList macro holds a list of the class member variables to pack, as shown here:
#define.CurrentVersion(1)
#localmacro.CurrentList
methodVariable1,
methodVariable2
#endmacro
canGoBatchJournal method
When a system administrator creates a new batch task by using the Batch Task form, the canGoBatchJournal method determines whether the batch task class appears in the list of available classes. For an example of how to use canGoBatchJournal.
Create a batch jobThe second step in developing a batch job is to create the batch job and add batch tasks. You can create a batch job in three ways:
■ By using the dialog box of a batch-enabled class
■ By using the Batch Job Designer form
■ By using the Batch API (It be will explained in another post)
The method you use depends on the degree of flexibility that you need and the complexity of the batch job. To create a simple batch job, consisting of a single task with no dependencies, you typically use the dialog box of a batch-executable class; to create a more complex batch job, consisting of several tasks that might have dependencies, use the Batch Job form; to create a highly complex or very large batch job, or one that needs to be integrated with other business logic, use the Batch API.
The following sections provide an example of using each method.
Create a batch job from the dialog box of a batch-executable class
The simplest way to run a batch-executable class as a batch job is to invoke the class by using a menu item. A menu item that points to a batch-executable class automatically opens a dialog box that lets
the user create a batch job. On the Batch tab of the dialog box, select the Batch Processing check box, as shown for the Change based alerts class in Figure below. When you select Batch Processing and click
OK, a new batch job with the task that represents the batch-executable class is created. The batch job then runs asynchronously at the date and time you specify. You can also set up recurrences or alerts
for the job by clicking the appropriate button on the right side of the dialog box. You can also specify the batch group for the task by using the drop-down list.
Create a batch job by using the Batch Job formYou can open the Batch Job form from several places. For example, you can open it by clicking Batch Jobs from System Administration > Inquiries > Batch Jobs or by selecting My Batch Jobs (for users) from Home > Inquiries > My Batch Jobs. Both menu items open the same form, but the information that is presented in the form differs, depending on the menu item that you use to open it. Depending on how you open the form and your level of access, you can view either the batch jobs that you have created or all batch jobs that are scheduled in the system.
Press Ctrl+N to create a new batch job, and then enter the details for the job in the grid or on the General tab: a description, and the date and time at which you want the job to start. You can also set up recurrence for the batch job by clicking Recurrence on the menu bar, and then entering a range and pattern for the recurrence.
Note If you don’t enter a date and time, the current date and time are entered automatically.
figure below show Batch Job Form
Batch tasks form
To create a task, do the following:
1. Press Ctrl+N to create the task.
2. In Task Description, enter a description of the task.
3. In Company Accounts, select the company in which the task runs.
4. In Class Name, select the process that you want the task to run. Classes appear in a lookup list containing all available batch-enabled classes. The lookup list appears only if the CanGoBatchJournal property is enabled.
5. In Batch Group, select a batch group for the task if necessary.
6. Save the task by pressing Ctrl+S.
7. Specify class parameters if necessary. As mentioned in previous sections, each batch task represents
a batch-executable class. Sometimes you need to set up parameters for that class.
For example, you might need to specify posting parameters for invoice posting. To do that, click Parameters on the menu bar in the Batch Tasks form. A dialog box specific to the selected class is displayed.
Note If you are creating a custom batch class, you must design the parameters form manually. If you implement a batch based on the SysOperation framework, this process is highly simplified. After you specify the necessary parameters and click OK, the class parameters are packed and saved in the Batch table and then are restored when the class executes.
8. Set up dependencies or advanced sequencing between tasks, if necessary.
After you create the batch job and add tasks to it, you can use the Batch Tasks form to define dependencies between the tasks. If no dependencies or conditions are defined within a job, the batch server automatically executes the tasks in parallel. (To configure the maximum number of parallel tasks, use the Maximum Batch Threads parameter in the Server Configuration form.)
If you need to use advanced sequencing to accommodate your business process flow, you can use either the Batch Tasks form or the Batch API. You can use these tools to construct complex dependency
trees that let you schedule batch jobs tasks in parallel, add multiple dependencies between batch tasks, choose different execution paths based on the results of the previous batch task, and so on.
For example, suppose that the job, JOB1, has seven tasks: TASK1, TASK2, TASK3, TASK4, TASK5, TASK6, and TASK7, and you want to set up the following sequence and dependencies for it:
■ TASK1 runs first.
■ TASK2 runs on completion (Ended or Error) of TASK1 (regardless of the success or failure of TASK1).
■ TASK3 runs on success (Ended) of TASK2.
■ TASK4 runs on success (Ended) of TASK2.
■ TASK5 runs on failure (Error) of TASK2.
■ TASK6 runs on failure (Error) of TASK3.
■ TASK7 runs on success (Ended) of both TASK3 and TASK4.
dependency tree for JOB
To define these task dependencies and to tell the system how to handle them, select a child task—for example, TASK2—from the preceding list, and then do the following:
1. In the Batch Tasks form, click in the Has Conditions grid, and then press Ctrl+N to create a new condition.
2. Select the task ID of the parent task, such as TASK1.
3. Select the status that the parent task must reach before the dependent task can run. For example, TASK2 starts when the status of TASK1 becomes Ended or Error.
4. Press Ctrl+S to save the condition.
5. If you enter more than one condition, and if all conditions must be met before the dependent task can run, select a condition type of All.
Alternatively, if the dependent task can run after any of the conditions are met, select a condition type of Any.
You can use the Batch Tasks form to define how the system handles task failures. To ignore the failure of a specific task, select Ignore Task Failure for that task on the General tab. If you select this option, the failure of the task doesn’t cause the job to fail. You can also use Maximum Retries to specify the number of times a task should be retried before it fails.
Imparted from Inside Dynamics AX 2012 Book.
1. Create a batch-executable class.
2. Create a batch job and define the execution schedule.
3. Configure a batch server and create a batch group. (It be will explained in another post)
4. Manage the batch job. (It will be explained in another post)
Create a batch-executable class
The first step in developing a batch job is to define a class that can be executed as a batch task. Many classes included with Microsoft Dynamics AX 2012 are already enabled for batch processing. You can also design a batch-executable class, as shown in the following example:
public class ExampleBatchTask extends RunBaseBatch
To run as a batch task, a class must implement the Batchable interface. The best way to implement the interface contract is to extend the RunBaseBatch abstract class, which provides much of the necessary
infrastructure for creating a batch-executable class. An alternative is to use the SysOperation framework, which provides additional advantages compared to extending the RunBaseBatch class. Will post more information about the SysOperation framework Later.
Table below describes the methods that must be implemented when you extend the RunBaseBatch class. The following sections describe these methods in more detail.
| Method | Description |
| run | Contains the core logic for your batch task |
| pack | Serializes the list of variables used in the class |
| unpack | Deserializes the list of variables used in the class |
| canGoBatchJournal | Determines whether the class appears in the Batch Task form |
run methodYou implement the core logic of your batch class in the run method. The run method is called by the batch framework for executing the task defined within it. You can run most of the X++ code in this method; however, there are some limitations on the operations that you can implement. For example, you can’t call any client logic or dialog boxes. However, you can still use the Infolog class. All Infolog and exception messages are captured when the batch class executes, and they are stored in the batch table. You can view these later in the Batch Job form or the Batch Job History form, both of which are located under System Administration > Inquiries > Batch Jobs.
Note If an error message is written to the Infolog, it does not mean that the task has failed; instead, an exception must be thrown to indicate the failure
pack and unpack methods
A class that extends RunBaseBatch must also implement the pack and unpack methods to enable the class to be serialized. When a batch task is created, its member variables are serialized by using the pack method and stored in the batch table. Later, when the batch server picks up the task for execution, it deserializes class member variables by using the unpack method. So it’s important to provide a correct list of the variables that are necessary for class execution. If any member variable isn’t packable, then the class can’t be serialized and deserialized to the same state.
The following example shows the implementation of the pack and unpack methods:
public container pack()
{
return [#CurrentVersion,#CurrentList];
}
public boolean unpack(container _packedClass)
{
Version version = RunBase::getVersion(_packedClass);
switch (version)
{
case #CurrentVersion:
[version,#CurrentList] = _packedClass;
break;
default:
return false;
}
return true;
}
The #CurrentList and #CurrentVersion macros that are referenced in the preceding code must be defined in the class declaration. Using a macro simplifies the management of variables in the class. If you add or remove variables later, you can manage the list by modifying the macro. The #CurrentList macro holds a list of the class member variables to pack, as shown here:
#define.CurrentVersion(1)
#localmacro.CurrentList
methodVariable1,
methodVariable2
#endmacro
canGoBatchJournal method
When a system administrator creates a new batch task by using the Batch Task form, the canGoBatchJournal method determines whether the batch task class appears in the list of available classes. For an example of how to use canGoBatchJournal.
Create a batch jobThe second step in developing a batch job is to create the batch job and add batch tasks. You can create a batch job in three ways:
■ By using the dialog box of a batch-enabled class
■ By using the Batch Job Designer form
■ By using the Batch API (It be will explained in another post)
The method you use depends on the degree of flexibility that you need and the complexity of the batch job. To create a simple batch job, consisting of a single task with no dependencies, you typically use the dialog box of a batch-executable class; to create a more complex batch job, consisting of several tasks that might have dependencies, use the Batch Job form; to create a highly complex or very large batch job, or one that needs to be integrated with other business logic, use the Batch API.
The following sections provide an example of using each method.
Create a batch job from the dialog box of a batch-executable class
The simplest way to run a batch-executable class as a batch job is to invoke the class by using a menu item. A menu item that points to a batch-executable class automatically opens a dialog box that lets
the user create a batch job. On the Batch tab of the dialog box, select the Batch Processing check box, as shown for the Change based alerts class in Figure below. When you select Batch Processing and click
OK, a new batch job with the task that represents the batch-executable class is created. The batch job then runs asynchronously at the date and time you specify. You can also set up recurrences or alerts
for the job by clicking the appropriate button on the right side of the dialog box. You can also specify the batch group for the task by using the drop-down list.
Create a batch job by using the Batch Job formYou can open the Batch Job form from several places. For example, you can open it by clicking Batch Jobs from System Administration > Inquiries > Batch Jobs or by selecting My Batch Jobs (for users) from Home > Inquiries > My Batch Jobs. Both menu items open the same form, but the information that is presented in the form differs, depending on the menu item that you use to open it. Depending on how you open the form and your level of access, you can view either the batch jobs that you have created or all batch jobs that are scheduled in the system.
Press Ctrl+N to create a new batch job, and then enter the details for the job in the grid or on the General tab: a description, and the date and time at which you want the job to start. You can also set up recurrence for the batch job by clicking Recurrence on the menu bar, and then entering a range and pattern for the recurrence.
Note If you don’t enter a date and time, the current date and time are entered automatically.
figure below show Batch Job Form
Batch tasks form
To create a task, do the following:
1. Press Ctrl+N to create the task.
2. In Task Description, enter a description of the task.
3. In Company Accounts, select the company in which the task runs.
4. In Class Name, select the process that you want the task to run. Classes appear in a lookup list containing all available batch-enabled classes. The lookup list appears only if the CanGoBatchJournal property is enabled.
5. In Batch Group, select a batch group for the task if necessary.
6. Save the task by pressing Ctrl+S.
7. Specify class parameters if necessary. As mentioned in previous sections, each batch task represents
a batch-executable class. Sometimes you need to set up parameters for that class.
For example, you might need to specify posting parameters for invoice posting. To do that, click Parameters on the menu bar in the Batch Tasks form. A dialog box specific to the selected class is displayed.
Note If you are creating a custom batch class, you must design the parameters form manually. If you implement a batch based on the SysOperation framework, this process is highly simplified. After you specify the necessary parameters and click OK, the class parameters are packed and saved in the Batch table and then are restored when the class executes.
8. Set up dependencies or advanced sequencing between tasks, if necessary.
After you create the batch job and add tasks to it, you can use the Batch Tasks form to define dependencies between the tasks. If no dependencies or conditions are defined within a job, the batch server automatically executes the tasks in parallel. (To configure the maximum number of parallel tasks, use the Maximum Batch Threads parameter in the Server Configuration form.)
If you need to use advanced sequencing to accommodate your business process flow, you can use either the Batch Tasks form or the Batch API. You can use these tools to construct complex dependency
trees that let you schedule batch jobs tasks in parallel, add multiple dependencies between batch tasks, choose different execution paths based on the results of the previous batch task, and so on.
For example, suppose that the job, JOB1, has seven tasks: TASK1, TASK2, TASK3, TASK4, TASK5, TASK6, and TASK7, and you want to set up the following sequence and dependencies for it:
■ TASK1 runs first.
■ TASK2 runs on completion (Ended or Error) of TASK1 (regardless of the success or failure of TASK1).
■ TASK3 runs on success (Ended) of TASK2.
■ TASK4 runs on success (Ended) of TASK2.
■ TASK5 runs on failure (Error) of TASK2.
■ TASK6 runs on failure (Error) of TASK3.
■ TASK7 runs on success (Ended) of both TASK3 and TASK4.
dependency tree for JOB
To define these task dependencies and to tell the system how to handle them, select a child task—for example, TASK2—from the preceding list, and then do the following:
1. In the Batch Tasks form, click in the Has Conditions grid, and then press Ctrl+N to create a new condition.
2. Select the task ID of the parent task, such as TASK1.
3. Select the status that the parent task must reach before the dependent task can run. For example, TASK2 starts when the status of TASK1 becomes Ended or Error.
4. Press Ctrl+S to save the condition.
5. If you enter more than one condition, and if all conditions must be met before the dependent task can run, select a condition type of All.
Alternatively, if the dependent task can run after any of the conditions are met, select a condition type of Any.
You can use the Batch Tasks form to define how the system handles task failures. To ignore the failure of a specific task, select Ignore Task Failure for that task on the General tab. If you select this option, the failure of the task doesn’t cause the job to fail. You can also use Maximum Retries to specify the number of times a task should be retried before it fails.
Imparted from Inside Dynamics AX 2012 Book.
No comments:
Post a Comment