BW_ACTIVATE_CHAIN

Use the BW_ACTIVATE_CHAIN script element to start a process chain, monitor processing, and store the logs in the activation report. You can specify various start conditions. If the process chain does not start immediately, but only following an event or at a certain time, these start conditions are logged. When the process chain starts, it is monitored until it ends. The process chain log is stored in the activation report. In addition, you can store individual process logs or process logs of background jobs. You can also trigger repeated attempts for the process chain to continue if there was interruption.

Transaction: RSA1

Syntax

BW_ACTIVATE_CHAIN

ID=...
[,NOFOUND=...]
[,ERROR=...]
[,PROCESSLOGS=...]
[,RESTART=...]
[,JOBLOGS=...]
[,LONGTEXT=...]
[,REPLICATE=...]
[,STATUSRETRY=...]
[,SCHEDULE=...]
[,SYNCHRONOUS=...]
[,GET_SPOOL=...]
[,COLLECTLOGS=...]

Parameters

• BW_ACTIVATE_CHAIN
  Starts a process chain, monitors processing, and stores the logs in the activation report

• ID=
  Technical designation of the process chain
  Format: script literal
• NOFOUND=
  (Optional) Handling if a process chain cannot be found
  Format: script literal
  Allowed values:
  • NORMAL (default)
    The script continues, the AE job ends normally
  • ABEND
    The script aborts, the AE job ends abnormally
• ERROR=
  (Optional) Handling if a process chain ends abnormally. This parameter is useful to restart process chains or their child processes. The advantage is that the job does not end and processing in a parent, such as a workflow, continues.
Format: script literal
Allowed values:
• ABEND (default)
  The script aborts, the AE job ends abnormally
• IGNORE
  The script continues, the AE job ends normally
• SUSPEND
  The job remains active until the process chain or its child processes have successfully been restarted, or if it has been canceled manually.
• PROCESSLOGS=
  (Optional) Output of the individual process logs of a process chain
  Format: script literal
  Allowed values:
  • YES (default)
    Individual process logs are added to the process chain log
  • NO
    Only the process chain log is output
  • ERROR
    Individual process logs are output only in case of error
• RESTART=
  (Optional) Number of attempts that are made to continue an interrupted process chain
  Format: integer
  Default: 0
• JOBLOGS=
  (Optional) Output of the process logs of the background job
  Format: script literal
  Allowed values:
  • YES (default)
    Process logs of background jobs are output
  • NO
    Process logs of background jobs are not output
  • ERROR
    Process logs of background jobs are only output if an error occurs
• LONGTEXT=
  (Optional) Output of the long text (diagnostics text) of a log message
  Format: script literal
  Allowed values:
  • ERROR (default)
    The long text of the log message is only output if an error occurs
  • YES
    The long text of the log message is output
  • NO
    The long text of the log message is not output
• REPLICATE=
  (Optional) Handling of the children of a process chain
  Format: script literal
  Allowed values:
  • NO (default)
    No replication takes place in the AE system.
  • YES
    Replicates the children of a job in the AE system. The children are displayed in the Process Monitoring perspective. Statistical records and reports are also generated in the AE system.
  • ALL
    Replicates all child processes of a job in the AE system including the ones that were skipped. The child processes are shown in the Process Monitoring perspective. Statistical records and reports are also generated in the AE system.
• STATUSRETRY=
  (Optional) Number of repeated status checks. Only after n repetitions, the Automation Engine will be informed that a process has ended.
  Format: number
  Default: 0
  Note: Due to a special SAP behavior, process chains may show the status "ended" for a short time and then continue. If the agent retrieves the status of a process chain exactly now, it would report the end of the process chain too early. To prevent this behavior, you can use the STATUSRETRY= parameter.
• SCHEDULE=
  (Optional) New scheduling of process chains
  Format: script literal
  Allowed values:
  • YES (default)
    The process chain is newly scheduled
  • NO
    No new scheduling takes place
    Doing so accelerates the start of the process chain.
• SYNCHRONOUS=
  (Optional) Executes process chains synchronously to start processing immediately
  Format: script literal
  Allowed values:
  • NO (default)
    No synchronous execution takes place
  • YES
    Executes the process chain synchronously
    
• GET_SPOOL=
  (Optional) Requests the spool list of the started job.
  Format: script literal
  Allowed values:
  • NO (default)
    The spool list is not requested
  • YES
    Requests the spool list
    The spool list is stored as a text file in the directory that has been defined in the INI file of the SAP Agent. The parameter that is used for this purpose is Download_dir= ([GLOBAL] section). The name of this file is structured as follows:
    <SAP job count>_<step number>_<spool number>.txt
    This file is also registered as job output in the AE job.
    For more information, see Agent SAP and Registered Job Output.
• COLLECTLOGS=
  (Optional) Writes the reports of the activated child processes of the process chain to the job report.

By default, the reports of replicated child processes are available in the job report AND in the task of the child process. You can decide not to store this information twice.
Allowed values:

• YES (default)
  Logs of child processes are written to the job report
• NO
  Logs of the child processes of the process chain are written to the job report
  

Note: The reports of the child processes are not available if you specify NO in the REPLICATE and COLLECTLOGS parameters .

Status Check

The Automation Engine expects that a final technical status is submitted when the agent verifies the status. The Interface Repository gives the following description:

The TECHSTATUS parameter represents the technical status of the request. It always contains one of the following values:

• G
  Green (request handling successful)
• Y
  Yellow (request is being processed)
• R
  Red (request incorrect or canceled)

However, these states are not final states. A status can change to red for a short time and then to yellow or green after a while. AE accounts for this fact. For status checks, you can activate a time delay to check n times if the status red actually remains in this status, for example. The INI file of the SAP Agent contains the parameters maxruntime= and repeat_check= in its [SAP_BW] section for this purpose.

Another function is available that checks the states of process chains. It supplies the following values:

• R
  cancel
• G
  normal end
• F
  normal end
• A
  continue checking
• X
  cancel
• P
  continue checking
• S
  cancel after the process chain has been restarted
• Q
  continue checking
• Y
  continue checking
• " "
  continue checking

The AE system then converts these states into return codes:

• 0
  Status: ENDED_OK
  SAP status: G or F
• 4
  Status: ENDED_NOT_OK
  SAP status: R
• 8
  Status: ENDED_NOT_OK
  SAP status: X
• 12
  Status: ENDED_NOT_OK
  SAP status: S

Examples

This example activates a process chain that has previously been queried by a user. The values for the relevant parameters in the script element result from this query. These values are assigned to the script element as script variables.

:BEGINREAD
:   READ &CHAIN#,"ZTEST,ZSBB1,ZSBB2",'Process chain','ZTEST',M
:   READ &ERROR#,"IGNORE,ABEND",'ERROR=','ABEND'
:   READ &NOFOUND#,"NORMAL,ABEND",'NOFOUND=','NORMAL'
:   READ &LT#,"YES,NO,ERROR",'LONGTEXT=','YES'
:ENDREAD

BW_ACTIVATE_CHAIN ID='&CHAIN#',ERROR='&ERROR#',NOFOUND='&NOFOUND#',LONGTEXT='&LT#'