After completing this lesson, you will be able to:

  • Understand fundamental RunList concepts
  • Understand RunList field definitions and relationships
  • Cancel a RunList process

RunList Overview

Throughout this couse, you’ve seen many different types of processes that take place in APM, such as transaction posting, payouts, and file sweeps. As you can imagine, each of these processes is quite complex, and consists of a number of sub-processes that run in sequence. You can keep track of these processes using RunLists. RunList records allow tasks within the process to transition to subsequent tasks. They also serve as a "breadcrumb trail" which allows processes to be reversed. RunList records are also logically grouped so that a user can get a complete picture of a process by reviewing the associated RunList records. Finally, RunList records contain valuable information the administrator can use for troubleshooting.

The RunList is both a form of auditing and a necessity for the processing framework. It contains all data relevant to a process that was executed. It shows what process was run, who initiated it, date and time, duration, parameters associated to the process and more.

While you can view RunLists in the RunList Management screen, this screen does not show all of the information you may need to trace a process. Generally, this is done using SQL queries to display the key fields.

RunList Levels

Each RunList contains multiple records organized in a hierarchy. Each record has a level that indicates its place in the process.

  1. Process Level is the top level RunList. Common Process Level RunLists include, but are not limited to, payouts, file sweeps, SQL scripts, and generate extracts. Since the process level RunList is the root level, you can identify these by comparing the RunListNoRoot field to the RunListNo field. If the values are the same, the RunList record is on the process level.
  2. Task Level RunLists define the components to be performed as part of the process. Common Process Level RunList records include, but are not limited to, payout tasks such as repost and extract, the File Sweep task, and the Finalize Payout task.
  3. Work Unit Level RunLists, also called threads, are used for the actual processing. A Work Unit RunList is created for every thread within a task.

    To view a RunList and associated records in the user interface:

  4. From the Administrator menu, select ToolsRunList Management
  5. Search for a RunList record by status, record type, name, or other criteria
  6. Select a RunList record
  7. Select the Tasks icon on the left pane

To view associated tasks, select the arrow next to Completed Tasks.


Individual tasks associated with the process are displayed, along with the Run ID for each task.


On the task level, the Messages icons are links to the error, warning, and informational messages. In the image below, selecting the Information hyperlink opens a new window that displays the message. A blue hyperlink indicates at least one message is available.

You can create an SQL query to return the number of messages generated from each thread. This is useful for running statistics and performance reports. Some key fields related to RunList messages are:

Field NameDescription
MsgAlwaysNumber of possible total message entries created during the run.
MsgInfoNumber of possible Informational message entries created during the run.
MsgWarningNumber of possible warning message entries created during the run.
MsgErrorNumber of possible Error message entries created during the run.

For example, the following query would return the number of informational messages (1) for the task shown in the image above:

Code snippet
SELECT RunListNo, RunListNoRoot, MsgInfo, RecType, ProSta, Name
FROM RunList
Where RunListNo = 15240689446860000

Key RunList Fields

It’s important to keep in mind that not all task levels and fields are displayed in the user interface. To view all details, including the work unit level records, you would use the SQL Workbench to create a query to display the records.

The following table contains the key fields on the RunList record. The full list of fields can be found in the Data Dictionary.

Field NameDescription
RunListNo or RunListIDThe unique identifier for the RunList record. It’s important to note that this field is not visible on the record; however, you can view it by querying the RunList table.
RunListNoRootPointer to the process level RunList in a series of process runs.
RunList Record TypeDescribes the type of process being run. Examples of record types include FileSweep, Computation, Payout, and Transaction Post Task.
RunListNoTaskParentThe Run ID for the Task Parent. This is the pointer to the Primary Level RunList which represents either the parent of the Task Level RunList represented by this record, or the grandparent of the Work Unit Level RunList represented by this record. This field is only populated on Task and Work Unit Level RunLists
RunListNoWuParentThe Run ID for the Work Unit Parent. This is the pointer to the Task Level RunList which represents the parent of the Work Unit Level RunList represented by this record. This field is only populated on Work Unit Level RunLists.
RecTypeThe Record Type. Identifies the type of process or task associated with this RunList. Examples include Pay (Payout) or RPOTRN (Repost Transaction).

The processing status of the record. This is displayed as a numeric value corresponding to the following values:

0 Open – The record is being established

1 Pending - The record has been inserted

2 In Process - The process is actively executing

3 Complete – The process has successfully completed

8 Warning – The process has completed, but one or more 'soft errors' were generated.

9 Error - The process encountered a 'hard error'.

NameThe name of the process. Examples include Payout, File Sweep or InFile Posting.
RecInThe number of records read in the process.
RecUpdThe number of records successfully processed.
RecRejThe number of records rejected in to an error state. The errors are displayed in the message log.

The elapsed time in milliseconds from start to finish for this task. Some performance analysis can be done by comparing RecIn/ElapsedTime.

Examples of RunList Queries and Results

Let’s look at examples of RunList queries using the fields listed above.

Example 1: Viewing RunList relationships in a Payout

In this example, we want to investigate the RunList for a single Payout process. In the image below, we used the SQL Workbench to display a RunList for a Payout. To return only the records for a single process, we filtered by the RunListNoRoot. The query looks like this:

Code snippet
SELECT RunListNo, RunListNoRoot, RunListNoTaskParent, RunListNoWuParent, RecType, ProSta, Name, RecIn, RecUpd, RecRej, ElapsedTime
FROM RunList
Where RunListNoRoot = 14525498240650000

First, note that the RunListNo and the RunListNoRoot (1) on the first row are the same. This record is the root of the RunList; in other words, it is the record on the Process level.

Next, note that the records below all have the same RunListNoRoot (2). This shows they are dependent on the Process, or root, level record.

Finally, note that some, but not all, records have a RunListNoWuParent value (3). These are Work Level Units, or Threads.

To the right, we can see the Record Type (shown as RecType), the Status (shown as ProSta), and the Name. The status of 3 means the task is complete.

Finally, the RecIn, RecUpd, and RecRej columns show the number of records read, processed and rejected, followed by the time elapsed. This can be very useful for performance troubleshooting. In the image below, it looks like we have no rejected records, and the elapsed time for the entire Payout process is 61103 ms, or about 61 seconds.

Example 2: RunList Relationships in a Partially Reversed Payout

In this example, we want to see the RunList details for a payout that has been partially reversed. For this, we used the following SQL query:

Code snippet
SELECT RunListNo, RunListNoRoot, RunListNoTaskParent, RunListNoWuParent, RecType, Reverse, ProSta, Name
FROM RunList
WHERE RunListNoRoot = 16848658402850000

Notice the Reverse column in the table above. The N means this is not a reversal; in other words, it’s a regular "forward" payout. The Y indicates the task associated with the reversal. The horizontal line shows the delineation between these two.

Notice that the RunListNoRoot value is the same for both. It seems like the reversal would have a different RunListNoRoot than the original payout since it’s a separate process, but APM assigns the same RunListNoRoot to the reversal in order to associate the reversal with the original payout.

Example 3: RunList Number Spawner (RunListNoSpawner)

Some Process Tasks are capable of starting other top level Processes. For example, a File Sweep task can start an InFileImportRequest, InFilePost and InEntityPost Process. The RunListNoSpawner marks those top level processes with the RunListNo of the Task which started them. This is a convenient way to trace which processes start another process.

Why is this helpful? Let’s say you are looking at a task level process with the type InFilePosting that is encountering an error, and you’d like to see which process is initiating this task. The query and result below shows that the RunListNoSpawner field matches the RunListNo field of the FileSweep process. This tells us the FileSweep initiated, or spawned, this task.

Let’s look at an example. We first ran a simple query to find the RunListNoSpawner value for the record:

Code snippet
SELECT RunListNo, RunListNoSpawner, RecType, ProSta, Name
FROM RunList

From the result, we found the InFilePosting task we want to trace.

Noting the RunListNo and the RunListNoSpawner, we can create a SQL query that finds a record with a RunListNo that matches the RunListNoSpawner:

Code snippet
SELECT RunListNo, RunListNoRoot, RunListNoSpawner, RecType, ProSta, Name
FROM RunList
(RunListNo = 15240689446860000
RunListNoSpawner = 15240689446860000)

This returns a result that includes the spawner; in this case, we can see that this is a FileSweep.

Cancelling a Process RunList

APM has the ability to cancel Processes through the RunList Management Screen; however, this functionality may occasionally not cancel the process as quickly as desired. It is possible to Force Cancel a process through the use of a SQL Script.

To cancel a Process, the following fields need to be updated:

  • Prosta: Set to 10 (Cancelled)
  • CancelReason: Set to something descriptive.
  • CancelUser: Set to your name or SQL Script
  • CancelDate: Set to current date (YYYYMMDD)
  • CancelTime: Set to CurrentTime using the RunList time format.
  • DatTo: Set to CurrentDate (YYYYMMDD)
  • TimeTo: Set to Current Time using the RunList time format.
  • FinalizeStatus: Set to P (Pending)
  • FullyReversed: Set to N (No).

To identify the records to cancel, you will need to identify the RunLists that are tied to the Process Level RunList (RunListNoRoot =xxx) and the Task Level Runlist (RunListNo=xxx). Additionally, you want to identify the RunLists that are InProcess (ProSta=2) or Pending (ProSta=1).

As an example, the following SQL will cancel the task with the number 15240689446860000, with the reason "InFilePosting Hung", on January 1, 2024. The user will be logged as "SQLScript".

Code snippet
SET ProSta = 10
CancelReason = ' InFilePosting Hung'
CancelUser = 'SQLScript'
CancelDate = 20240101
CancelTime = 91312864
datto = 20240101
timeto = 91312864
finalizestatus = 'p'
fullyreversed = 'n'
WHERE (runlistno=15240689446860000 pr runlistnoroot = 15240689446860000
AND prosta in (1,2)

Log in to track your progress & complete quizzes