SAP Extractor Management

You can use Control-M for SAP Extractor Management to create one mirror-image job or more, by using criteria identical to that of specific jobs already running in SAP. These jobs are then monitored (but not submitted), enabling Control-M to track the progress of the actual job in SAP. This mirror image is stored in Active Jobs in the Control-M/Server.

These procedures are relevant for SAP configuration profiles that are configured with XBP 3.0.

Configuring SAP Extractor

This procedure describes how to set the priority level of SAP job types, which enables Control-M for SAP to handle jobs that match more than one job type. Extracted jobs cannot have a priority that is higher than Intercepted or Spawned jobs.

Before you begin

If you want to detect Spawned jobs, then you need to define an SAP R3 or SAP Process Chain job, as defined in the job definition The set of parameters that defines what the job does, when it runs, its prerequisites, and the post-processing actions that Control-M performs after the job completes execution.. To assign Intercepted Jobs a priority, ensure that at least one CTM Interception Rule is selected.

Begin

From the icon, select Configuration.
From the drop-down list, select Plug-ins.

The Plug-ins tab appears.
Select the required SAP plug-in, and then, from the Configuration drop-down list, select Extractor Management.

The SAP - Configuration Management pane appears.
In the General Configuration area, for each job type field, select the required priority from the drop-down menu. If you do not want to have a job type detected, then select Do Not Detect.
To enable the logging of Extractor Management activities, toggle Activity Log on.

The activity log file is saved in the Control-M/Agent proclog directory in the following format:

xt_log_<YYMMDD>
In the Interval Time field, enter the required number of seconds between the loop cycles of the Extractor.

Default: 120 seconds
In the Extractor Alert Settings area, if you want to receive an alert A notification about the status of a job or component that appears in the Alerts window. in the Control-M Alerts window when the Extractor process stops unexpectedly, toggle Enable Alert on (this is the default). You can select the severity of the alert and the interval between alerts (default interval is 5 minutes).
In the Extractor Definitions area, in the Connection Profile Name field, select the required connection profile.

The SAP interception profiles table for the selected connection profile name is loaded, and areas appear as follows:
- If the connection profile is configured with XBP 3.0, then the SAP Interception Profile, CTM Interception Profile, and Extraction Criteria areas appear.
- If the connection profile is configured with XBP 2.0, then the SAP Interception Criteria, CTM Interception Rules, and Extraction Criteria areas appear.
If you do not want Control-M to add a default Interception Rule, then toggle Do not add a default Interception Rule on.
Do one of the following:
- For a connection profile configured with XBP 3.0, in the SAP Interception Profile area, in the Active Profile area, click Load, and then select the active profile by doing one of the following:
  - If you do not want to select an active interception profile, then, from the drop-down list, select None.
  - If you want to select an active interception profile, then, from the drop-down list, select the profile.
  - Create an interception profile, as described in Creating an SAP Interception Profile.
  - To edit a profile, go to the profile in the drop-down list, and then click .
    
    You cannot edit the active interception profile. If you want to edit this profile, then first select another profile as the active.
- For a connection profile configured with XBP 2.0, in the SAP Interception Criteria area, in the Active Rule area, click Load, and then select the active interception rule by doing one of the following:
  - If you do not want to select an active interception rule, then, from the drop-down list, select None.
  - If you want to select an active interception rule, then, from the drop-down list, select the rule.
  - Create the interception rule, as described in Creating an SAP Interception Rule.
  - To edit a rule, go to the profile in the drop-down list, and then click .
    
    You cannot edit the active interception rule. If you want to edit this rule, then first select another rule as the active.
In the CTM Interception Profiles area (for connection profiles with XBP 3.0) or the CTM Interception Rules area (for connection profiles with XBP 2.0), select the rule for running intercepted jobs by doing one of the following:
- If you want an existing rule, then, from the Rule for running intercepted jobs drop-down list, select the rule.
- Create the rule, as described in Adding Interception Rules to Control-M.
Add job extraction criteria, as described in Adding a Job Extraction Criterion.
Add job extraction rules, as described in Adding Rules for Extracting SAP Jobs.
Restart the Agent.
To start using the Extractor, start the Extractor process as described in Starting and Stopping the Extractor Process.

Creating an SAP Interception Profile

This procedure describes how to create an SAP interception profile, which is part of Configuring SAP Extractor when the connection profile is configured with XBP 3.0. The profile is comprised of rules, and each rule is comprised of criteria, as can be done using the CRIT SAP Transaction.

Before you begin

In the Extractor Definitions area, select the required Connection Profile from the Connection Profile Name drop-down list.

Begin

In the SAP Interception Profile area, click .

The Add SAP Interception Profile pane appears.
Enter the Profile Name.
In the Rule Hierarchy area, complete the hierarchy of criteria by clicking on the level of the rule and on the level of the criterion. Using the toggle, define the rule as AND or OR.
For each criterion, add the criteria details by doing the following:
1. From the Rule Hierarchy, select the rule.
2. In the Criteria Details area, click Add Row, and then select one or more of the following types of rows:
  - Client
  - Job Class
  - Job Creator
  - Job Name
  A table appears for each row.
3. Complete the tables as required.
After you complete the criteria hierarchy, click Add.

The new SAP interception profile is created.
Restart the Agent.

Creating an SAP Interception Rule

This procedure describes how to create an SAP interception rule, which is part of Configuring SAP Extractor when the connection profile is configured with XBP 2.0.

Before you begin

In the Extractor Definitions area, select the required Connection Profile from the Connection Profile Name drop-down list.

Begin

In the SAP Interception Criteria area, click .

The Add SAP Interception Rule pane appears.
Enter the Job Name and User.
Click Add.

The new SAP interception rule is created.
Restart the Agent.

Adding Interception Rules to Control-M

This procedure describes how to add Control-M interception rules so that the intercepted jobs are put on hold in Scheduled status until they are released by Control-M. This is part of Configuring SAP Extractor.

Before you begin

In the Extractor Definitions area, select the required Connection Profile from the Connection Profile Name drop-down list.

Begin

In the CTM Interception Profiles area (for connection profiles with XBP 3.0) or the CTM Interception Rules area (for connection profiles with XBP 2.0), click .

The Add SAP Interception Rule pane appears.
For each parameter, type or select the required value, as described in SAP Interception Rule Parameters.
- Consider how you specify Job Name and User parameters. Definitions that are too general (for example, entering * in both fields), could cause the system or other user jobs to be intercepted.
- Ensure that you have no more than one connection profile that uses Interception rules using the same system and client.
Click Add.

The new Control-M interception rule is created.
Restart the Agent.

SAP Interception Rule Parameters

The following table describes the parameters for adding SAP interception rules in the CTM Interception Profiles area (for connection profiles with XBP 3.0) or the CTM Interception Rules area (for connection profiles with XBP 2.0), as described in Adding Interception Rules to Control-M.

Area or Parameter	Description
Job Name	Defines the SAP job to be extracted from SAP to Control‑M. Any generic value is valid. You can use the * wildcard, for example: JOB_* In a SAP job, SAP perceives an underscore "_" and a space to be the same character. This means that two jobs, named respectively JOB STAR and JOB_STAR, for example, would be recognized as the same job. This is a known SAP problem.
User	Defines the name of the SAP user that created the job. You can use the * wildcard.
Program	Defines the program that is used by the SAP job. You can use the * wildcard. BMC recommends that you use the * wildcard.
Into Folder	Determines the Control-M folder where the job is submitted, as follows: None: Does not add the job to a folder. Recent: Adds the job to the folder that was most recently run. Standalone: Run the job by adding it to a folder. New Folder: Adds the job to a new folder. Selected: Sets a folder run ID The identification code for a SMART folder, sub-folder, or job execution. and adds the job to the folder. Specify the folder in the Folder Run ID field. The last four options are similar to the strong Force Into options of Control-M/EM. For more information about Control-M folders and Force Into parameters, see Using Control‑M Workload Automation.
Creating the intercepted jobs in Control-M	Defines how intercepted jobs are created in Control-M.
Method	Determines the method for creating the intercepted jobs in Control-M, as follows: Template: Defines the name of an existing Control-M SAP folder and job to be used as a template for creating the job in Control-M. Specify the folder in Folder Name and the job in Job Name. User Exit: Defines the path to an executable or script file that includes user-specific definitions about how to create the intercepted jobs in Control‑M. Specify the executable or file in the A pre-defined executable or script file drop-down list. For more about User Exit, see User Exit Definition.

Adding a Job Extraction Criterion

This procedure describes how to define an extraction criterion for the kinds of SAP job that Control-M must extract from SAP. All jobs that have this criterion are extracted from SAP and mirrored in Control‑M. This is part of Configuring SAP Extractor.

Before you begin

In the Extractor Definitions area, select the required Connection Profile from the Connection Profile Name drop-down list.

Begin

In the Extraction Criteria area, click Add a job Extraction Criterion.

The Add Extraction Criterion pane appears.
For each parameter, type or select the required value, as described in SAP Extraction Criteria Parameters.
Click Add.
The extraction criterion is added.
Restart the Agent.

SAP Extraction Criteria Parameters

The following table describes the parameters for adding SAP extraction criteria, as described in Adding Interception Rules to Control-M.

Parameter	Description
Job Name	Defines the name of the job in SAP, which can be either a specific or a generic name. Any generic value is valid. You can use the * wildcard, for example: JOB_* In a Job Name, SAP perceives an underscore "_" and a space to be the same character. This means that two jobs, named respectively JOB STAR and JOB_STAR, for example, would be recognized as one and the same job. This is a known SAP problem.
User Name	Defines the owner of the job in SAP. Any generic value is valid, for example: Y
Job Group	Defines the group where the jobs belongs.
Job Count	Defines the CCMS job number. Rules: 8-digit number
With Pred	Defines the selection flag for jobs with start after predecessor. Rules: Valid values are: X/N
Event ID	Defines the background event ID.
Event Param	Defines the background event parameter.
From Date	Defines the scheduled start date for the CCMS job. Rules: Valid format: YYYYMMDD
From Time	Defines the scheduled start time for the CCMS job. If From Date and To Date are the same date, then From Time defines the scheduled start time for the CCMS job. Rules: Valid format: HHMMSS
To Date	Defines the scheduled end date for the CCMS job. Rules: Valid format is: YYYYMMDD
To Time	Defines the scheduled end time for the CCMS job. If From Date and To Date are the same date, then To Time defines the scheduled end time for the CCMS job. Rules: Valid format: HHMMSS
No Date	Determines whether the job has no start date. Rules: Valid values are: X/N
Statuses	Defines the status of the CCMS job, as follows: Released Ready Finished Scheduled Active Canceled

Adding Rules for Extracting SAP Jobs

This procedure describes how to add extraction rules to determine which SAP jobs are extracted and how they are represented in Control‑M. These rules are defined for each job extraction criteria type.This is part of Configuring SAP Extractor.

Before you begin

In the Extractor Definitions area, select the required Connection Profile from the Connection Profile Name drop-down list.

Begin

In the Extraction Criteria area, click Add an Extraction Rule.

The Add Extraction Rule pane appears.
Complete the parameters as described in SAP Extraction Rule Parameters.
- Consider how you specify Job Name and User parameters. Definitions that are too general (for example, entering * in both fields), could cause the system or other user jobs to be intercepted.
- Ensure that you have no more than one connection profile that uses Interception rules using the same system and client.
Click Add.

The extraction criterion is added.
Restart the Agent.

SAP Extraction Rule Parameters

The following table describes the parameters for adding an SAP extraction rule, as described in Adding Interception Rules to Control-M.

Parameter	Description
Job Name	Defines the name of the job in SAP, which can be either a specific or a generic name. Any generic value is valid. You can use the * wildcard, for example: JOB_* In a Job Name, SAP perceives an underscore "_" and a space to be the same character. This means that two jobs, named respectively JOB STAR and JOB_STAR, for example, would be recognized as one and the same job. This is a known SAP problem.
Into Folder	Defines the Control-M folder where the job is submitted, as follows: None: Does not add the job to a folder. Recent: Adds the job to the folder that was most recently run. Standalone: Run the job by adding it to a folder. New Folder: Adds the job to a new folder. Selected: Sets a folder Run ID and adds the job to the folder. Specify the folder in the Folder Run ID field. The last four options are similar to the strong Force Into options of Control-M/EM. For more information about Control-M folders and Force Into parameters, see Using Control‑M Workload Automation.
Creating the Extracted jobs in Control-M	Defines how extracted jobs are created in Control-M.
Method	Defines the method for creating the extracted jobs in Control-M, as follows: Template: Defines the name of an existing Control-M SAP folder and job to be used as a template for creating the job in Control-M. Specify the folder in Template Folder Name and the job in Template Job Name. User Exit: Defines the path to an executable or script file that includes user-specific definitions about how to create the extracted jobs in Control‑M. Specify the executable or file in the A pre-defined executable or script file drop-down list. For more about User Exit, see User Exit Definition.

User Exit Definition

If you are processing intercepted (as configured in SAP Interception Rule Parameters) or extracted jobs (as configured in SAP Extraction Criteria Parameters), then you can do one of the following:

Extract the jobs to the Control-M environment.
Assign a different way to process these jobs.
Restart the Agent.

A user exit is a user-defined script (or executable) that can be used for this purpose. This file must exist in the USER_EXIT directory, which is located in the Control-M/Agent directory, under CM/SAP.

For each intercepted or extracted job, the Extractor Management utility runs the script, and passes a list of parameters with values of the specific intercepted or extracted job. The values are as follows:

Parameter Number	Parameter Value
1	<SAP Job Name>
2	<Job count>

A successful return value of the script is 0 (zero). Any other return value causes the job to be intercepted or extracted again, at the next iteration of the Extractor Management utility.

The User Exit script can run a user-defined action, and can use other Control-M utilities (for example, ctmorder and ctmcreate) to handle the Extracted or Intercepted job.

Pre-defined User Exit for the Extractor Management Utility

Extractor Management automatically defines a default CTM Interception Rule that avoids discarding intercepted jobs.

This Interception Rule calls a pre-defined User Exit script with the following name and location:

UNIX: <Agent_homedir>/ctm/cm/SAP/exe/default_order
Windows: <Agent home directory>\CM\SAP\EXE\default_order.bat

This User Exit script is called by the default Interception Rule if the intercepted job has not met the conditions of any preceding rule.

This script submits the job using the Control-M ctmcreate command. You can use this script as one example of how to create a User Exit.

Starting and Stopping the Extractor Process

This procedure describes how to start the Extractor process, which is the last step in Configuring SAP Extractor, and to stop it.

Begin

After you have completed Extractor configuration, you can start and stop the Extractor process as follows:

Action	OS	Procedure
Start	UNIX	From a command prompt type the following command: start-xt
Start	Windows	Select Start > Settings > Control Panel > Administrative Tools > Services. Select Control-M for SAP <AGENT INSTANCE> Extractor, and then click Start.
Stop	UNIX	From a command prompt, type the following command: shut-xt If the computer on which Agent is installed is rebooted while the Extractor process is active, then the Agent automatically restarts the Extractor Management utility.
Stop	Windows	Select Start > Settings > Control Panel > Administrative Tools > Services. Select Control-M for SAP <AGENT INSTANCE> Extractor, and then click Stop.