Configuration of IDoc Channels
IDocs (Intermediate Documents) are standard containers for exchanging data between applications. Between SAP applications they are transferred using the ALE (Application Link Enabling) layer which again uses either tRFC or File technology as the underlying technique.
An IDoc contains different types of information. It contains the application data to be exchanged (e.g. a sales orders) as well as technical data providing information from where to where the IDoc is supposed to be sent. Furthermore, the IDoc also contains status information that shows which processing step within the data exchange the IDoc is currently in. These statuses can indicate error situations or success situations. Some of them can be intermediate statuses that are indicating backlog situations.
For an end-to-end ALE monitoring it is necessary to monitor the various IDoc statuses in the outbound as well as the inbound direction.
The IDoc monitoring functions in IF Monitoring enable you to restrict the monitoring to specific IDoc interfaces based on the IDoc’s header and status information. The monitoring intends to report on errors and growing backlogs for these specific IDoc interfaces on the one hand (monitoring template “IDoc (Real-time Monitoring)”), and to provide statistical data on the IDoc traffic like the throughput and the performance of IDoc processing on the other hand (monitoring template “IDoc (Analysis)”). If needed the monitoring can also be restricted to certain IDoc contents which enables you to increase the granularity of the monitoring even more.
Interface Channel Configuration
Available Monitoring Templates
The following templates are available to monitor IDoc processing on the managed system:
The decision which monitoring template you want to set up is made during the creation of the interface channel.
In the case of IDoc channels you can change the template of the channel later on by clicking on the link for the template. But note that all metric selection will be reset during this selection.
System Requirements
The following technical prerequisites have to be met in order to use this template:
Monitoring Template “IDoc (Real-time Monitoring)”
Available Metrics
This monitoring template provides metrics to monitor IDoc errors and IDoc throughput.
Configuration
Configuration on Interface Level
When setting up an IDoc channel you have two configuration levels. The first level is the configuration on interface level. Here you enter selection criteria to select the specific IDocs you want to monitor. These selection criteria can select the IDoc based on header data, but also on information in the data segments. The second level is the monitoring of the status codes for the selected IDocs.
On Interface level the parameters “Direction” and “IDoc Age (in hours)” are mandatory.
The information needed to maintain header information of the managed objects can be found either by viewing the control record of an example IDoc (BD87), in transaction WE20, WE05, or directly in table EDIDC.
Wildcards can be used in all select-option fields. Click the button "Expert Mode" to display all available parameters.
The following fields are available to define which IDocs are considered:
Configuration on Metric Level
Once you have set up the selection criteria for the IDocs you are interested in, you can select the key figures you are interested in.
For each metric you can maintain the following restrictions for the IDoc status segments:
Threshold Configuration
The thresholds and the data collection settings are maintained in the next step "Activation" of the IFMon setup. When setting up the thresholds please note that due to historic reasons not all threshold types are supported. The recommended rating strategies for IDoc metrics are “Info Only”, “Numeric Threshold (Green/Yellow/Red)” and “Range Threshold”.
Using the "Detail Info" List
In case of an IDoc alert it is desirable to have direct access to these IDocs without having to search for them in the managed system via WE05 or BD87. For this purpose the "Detail Info" view was developed also for IDocs.
The "Detail Info" function allows you to display IDoc details in different views. “Error View (Alerted IDocs)” is displayed by default when you first call this function. As the name indicates, this view contains information about all IDoc errors that triggered the selected alert. Once in the function you can switch the the "Content View (Alerted IDocs)" which contains information on monitored segments.
You can access the "Detail Info" list via the metric information in the alert details for the real-time monitoring alerts.
Once you have entered the detailed display, you can switch between the “Error View” and “Content View” using the corresponding push-buttons.
Both views show specific IDoc properties. The following columns remain the same in both views:
- IDoc number
- Message Type
- Current Status Number
- Status Group (traffic light grouping)
- Age of last status change: This column displays the time since the IDoc resides in its current status.
- Error Resolution Time: This time indicates how long it took to put the IDoc into an uncritical status after it has entered a critical status for the first time. The typical use-case would be that you monitor failed IDocs (like IDoc status 51), and you like to be informed on the time it took to resolve the error, this means, to put the IDoc to successful status 53. In a more general context, the terms “critical status” and “uncritical status” refer to the status numbers you have configured. Each status number which is part of the monitoring setup is regarded as a “critical status” (although you might monitor successfully created IDocs), and each status number which is not part of the configuration is regarded as “uncritical”. If, after entering a critical status for the first time, the IDoc is not processed any further, the point in time you call the detail info is used to calculate the Error Resolution Time.
Error View
The “Error View” displays the following additional IDoc properties:
- Status Message Text of displayed status
- Status Message Number of displayed status
- Status Message ID of displayed status
Content View
The “Content View” provides information about selected IDoc contents:
- Count Segment: <segment name> (as specified in the “Count Segment” parameter during monitoring configuration): displays the number of specified segments per IDoc
- Values of Field: <segment name> - <field name> (as specified in the “Field Name 1/2" parameter during monitoring configuration): Content of these fields within the IDoc (either as specified in parameter “Field Value 1/2", or all field values)
You can also choose between the modes “Alerted IDocs” and “All IDocs”. As previously stated, “Alerted IDocs” lists all IDocs that triggered the alert from which you called the detailed display (provided that the IDoc Age has not yet been exceeded; see above). The current status of these IDocs is displayed so that you can see whether the problem still exists or whether it was solved between when the alert was raised and the detail display was called.
In order to display more detailed information on the alerted IDocs, and also to enable error handling, several additional functionalities can be accessed from the detail display functionality.
- Display IDocs (WE05): Select one or more IDocs (by highlighting the relevant rows) that are to be displayed in standard monitoring transaction WE05. This function is also offered for single IDocs when you double-click the IDoc row.
- Display Inbound Queue (WEINBQUEUE): For inbound IDocs which are processed in a serialized manner via qRFC, the IDocs might get stuck during queue processing, residing in status 75. For such IDocs you can display the corresponding inbound qRFC queue to which the IDoc belongs to, and search for the reason the inbound queue is being blocked.
- Start Inbound Queue: By pushing this button you can start a blocked inbound qRFC queue using the standard report RSEINBQUEUE_PARTNER. This action can only be performed for IDocs in status 75. Be aware that the root cause for the blocked queue has to be resolved first (e.g. another IDoc might block the queue which has to be corrected first), otherwise the restart of the queue does not affect anything.
- Refresh Display: Refreshes the current display and updates the current status of the IDoc, the status age and the error resolution time.
- IDoc Statistics: This info box provides a brief summary of the IDocs currently displayed (depending on the mode “Alerted IDocs” or “All IDocs”):
- Number of alerted / all IDocs
- Number of Segments (only visible in case parameter "Count Segment" was configured)
- Age of oldest IDoc
- Age of newest IDoc
- Distinct Message Types with occurrence (the five message types that occur most frequently)
- Distinct Receiver Partners with occurrence (the five receiver partners that occur most frequently)
- Distinct Sender Partners with occurrence (the five sender partners that occur most frequently)
- Monitoring Configuration: This info box displays the complete configuration for the parameter set for which you called the detail info.
Monitoring Template “IDoc (Analysis)”
Available Metrics
Besides standard monitoring and alerting the metrics of this template can also feed the reporting tools Business Process Analytics and BPO Dashboards.
Configuration
Configuration on Interface Level
As for the real-time monitoring you have again two setup levels. On the interface level you set up the selection criteria to select the IDocs you are interested in.
The parameters "Direction" and "Selected Time Frame" are mandatory. Wildcards can be used in all select-option fields.
For some parameters you can select the "Group-by" flag (the checkbox next to the parameter input field). If this flag is set one metric variant will be created for each distinct parameter value.
The following fields are available to define which IDocs are considered:
The selection parameters “Selected Time Frame” and “End of Time Frame” define the time window for which IDocs should be evaluated on the managed system. As a minimum input “Selected Time Frame” has to be filled which sets the maximum age for the IDocs. Optionally you can provide an input for parameter “End of Time Frame”, which sets the minimum age of the IDocs. If you leave this parameter blank all IDocs up to the point of data collection are evaluated.
For historic reasons parameter “Selected Time Frame” can be filled with values TD (to monitor the whole current day) or YD (to monitor the whole day yesterday). Apart it is possible to monitor dynamic time ranges. The parameter has to be maintained in the following way:
Syntax = {Placeholder}{Operator}{Offset}
The {Placeholder} has to be prefixed by a "$" sign. The optional {Offset} is entered as an integer value after the {Operator}. For {Operator}, you can choose the following signs:
"-": decrements the offset
"+": increments the offset
For the placeholder, the following keywords are available:
1) Any offset for placeholder $DELTA is ignored, and you cannot use it with an entry in the "End of Time Frame" parameter. In delta mode, the data collector gets all IDocs which were created since the last data collection, up to the current time.
Configuration on Metric Level
The input parameters on metric level depend on the selected key figure.
For each of the key figures you can maintain additional filters on metric level.
The metrics of monitoring template “IDoc (Analysis)” provide several parameters which enable you to further filter the IDocs which have already been pre-selected based on their header data. Basic and mandatory information is the status number which you intend to monitor. For count and percentage metrics you can provide more than one status number using the select-options functionality. This enables you e.g. to monitor all IDocs which have been created in an erroneous inbound status (like status numbers 51, 56, 60, 65, 66) at the same time. The processing time metrics expect two single status numbers, the initial and the final status, between which the processing time is to be calculated.
Metrics: Total number of erroneous IDocs (Analysis), Total number of processed IDocs (Analysis), Current number of erroneous IDocs (Analysis), Current number of processed IDocs (Analysis)
These metrics measure the number of IDocs created within a specified time frame. The IDocs to be taken into account are defined by the header information you maintain on interface level, and based on the status record details that can be maintained on metric level.
For the “Total Number” metrics, an IDoc contributes to the measured value as soon as it took over one of the specified statuses at least once during its processing. This means, the current status of the IDoc does not necessarily has to be one of the specified statuses; all status records are considered. In contrast, the “Current Number” metrics counts only those IDocs whose current status is one of the statuses as provided in parameter “Status Number(s)”.
On metric level you have to provide at least mandatory parameter “Status Number(s)”. Wildcards can be used in all select-option fields.
1) Only available for the “Current Number” metrics
Metrics “Average Time to Process IDocs (Analysis)” and “Maximum Time to Process IDocs (Analysis)”
These metrics measure the IDoc’s processing time between two status numbers (“initial and final status”) and return either the average processing time for all IDocs, or the maximum time it took to process one of the IDocs out of the subset of all matching IDocs. The IDocs to be taken into account are defined by the header information you maintain on managed object level, and based on the status record details that can be maintained on metric level.
On metric level you have to provide at least mandatory parameters “Initial Status Number” and “Final Status Number”. Wildcards can be used in all select-option fields.
1) Only available for metric “Average Time to Process IDocs”
Metrics “Percentage of IDocs in total (Analysis)” and “Percentage of Current IDocs (Analysis)”
These metrics calculate the percentage of IDocs created in a specified status within a given time frame. In order to calculate the percentage, the number of matching IDocs (having one of the specified status(es)) is compared against the number of all IDocs created the same day in the same interface (i.e all IDocs which have the same IDoc header criteria):
For metric “Percentage of IDocs in total (Analysis)”, an IDoc contributes to the measured value as soon as it took over one of the specified statuses at least once during its processing. This means, the current status of the IDoc does not necessarily have to be one of the specified statuses; all status records are considered. In contrast, the metric “Percentage of Current IDocs (Analysis)” considers only those IDocs whose current status is one of the statuses as provided in parameter “Status Number(s)”.
On metric level you have to provide at least mandatory parameter “Status Number(s)”. Wildcards can be used in all select-option fields.
1) Only available for metric “Percentage of Current IDocs (Analysis)”
Threshold Configuration
As for the real-time monitoring the thresholds are set in the step "Activation". Also here you should stick to the threshold types “Info Only”, “Numeric Threshold (Green/Yellow/Red)” and “Range Threshold”.
The monitor checks the status record of the selected IDocs and counts the number of IDocs that meet the selection criteria and are in the respective status. Depending on the key figure different statuses could be interesting. In the
graphic in the beginning of this wiki page all status in RED are real error status, while the status in YELLOW are intermediate status. An IDoc usually passes these intermediate statuses in its lifetime, so this doesn't mean a problem, however a very high or growing number of IDocs in intermediate status can indicate a backlog (e.g. a problem on ALE level).
We have two different types of key figures for exceptions and performance, Delta number and Total number monitors.
- Delta number monitors only take IDocs into account that are "new" in this the monitored status since the last collector run. The "Current number of erroneous IDocs (Real-time) (Delta)"monitor should be used for error monitoring as it will alert on each new error since the last collector run, but not alert on the same error twice.
- Total number monitors take all IDocs in a certain status into account up to the maximum IDoc age. The "Current number of erroneous IDocs (Real-time) (Total)" monitor should be used to detect a growing number of IDocs in an intermediate state, to detect if there is a backlog building up in the system.
Which statuses should be monitored depends very much on your individual ALE scenario and your past experience with IDoc processing.
In the following we will highlight statuses that are considered as being critical and are recommended to be monitored. Additionally it is recommended to check for errors or backlog situations in the past and include those into the monitoring concept, if necessary.
Outbound IDoc Monitoring
Error Monitoring
The following statuses are considered error statuses and should be monitored for error monitoring.
If ALE-Audit is used also the status 40 should be monitored representing application errors. The status is the status on the receiver system.
If converters (e.g. Seeburger, SAP Business Connector etc.) are used, the following statuses are relevant for technical error monitoring.
Backlog Monitoring
The following intermediate statuses should be considered for backlog monitoring.
For a backlog monitoring the parameter “Status Age” needs to be considered. In some ALE scenarios the IDocs will be processed immediately and in other scenarios the IDocs are gathered and processed by background jobs (e.g. every 60 minutes). Therefore it makes sense to set the parameter for status age to e.g. 60 minutes in order to avoid being alerted because of an intermediate backlog situation.
If ALE-Audit is used also the status 39 on the receiver system should be monitored.
Inbound IDoc Monitoring
Error Monitoring
The following statuses are considered error statuses and should be monitored for error monitoring.
Monitoring for Application Errors
Monitoring for Technical Errors
Backlog Monitoring
The following intermediate statuses should be considered for backlog monitoring.
For a backlog monitoring the parameter “Status Age” needs to be considered.
How to Work with “IDoc (Analysis)” Parameters on Metric Level
This section contains additional information on the behavior of the parameters on metric level for the IDoc Analysis. You will also find some example monitoring scenarios here.
Parameter "Status Counter"
If you are interested in monitoring not the first occurrence of a certain status number (e.g. as the IDoc might be subject to automated reprocessing in failure case), you can set the “Status Counter” parameter to a finite value. Then only IDocs are alerted which fulfill this additional condition.
Parameter "Minimum Status Age"
For metrics “Current number of erroneous IDocs (Analysis)”, “Current number of processed IDocs (Analysis)” and “Percentage of current IDocs (Analysis)” it is also possible to provide a “Minimum Status Age” in minutes. If this parameter is set the creation time-stamp of the current status is checked against the settings in this parameter. Only if the current status resides longer in this status than specified in “Minimum Status Age”, the IDoc is taken into consideration.
This way you avoid to be alerted too early on a certain critical situation. For example, if you like to monitor intermediate statuses, you might be interested only in IDocs which do not leave this intermediate status as expected, but remain in this status too long.
Parameter "Minimum Processing Time"
The “Minimum Processing Time” parameter enables you to restrict the data collection only to long-running IDocs, which took more time to reach the “Final Status Number” since their creation than specified in the “Minimum Processing Time” parameter.
Parameters for the IDoc Content
The following further parameters are available aiming at the content of the IDoc status message:
- Status Message Qualifier
- Status Message ID
- Status Message Number
- Relevant Status Record
The first three parameters can be used to filter the IDocs by a certain status message (e.g. if you only want to be alerted for a specific application-related error the IDoc runs into). The “Relevant Status Record” parameter enables you to define which of the matching status records are to be queried against the status message parameters. Three options exist:
- First status record with matching status: The first status record (in chronological order) which matches the IDoc header conditions and has the right status number is checked against the status message parameters.
- Last (current) status record: The last status record (in chronological order) which matches the IDoc header conditions and has the right status number is checked against the status message parameters.
- First status record with matching status considering Status Counter: This option takes into account the settings of the “Status Counter” parameter. This means, if the “Status Counter” parameter is set to a finite value, the data collector checks the status message of the first relevant status record which fulfills the status counter condition. For example, if you have set “Status Counter” to value 2, then the second matching status record within the IDoc’s status record chronology is checked whether it fulfills the status message parameter conditions. Note: if you use this option but leave the “Status Counter” parameter blank, then the data collector behaves as if option “First status record with matching status” has been chosen.
In the following you can find some monitoring scenarios which illustrate the data collection logic for the status record search as explained in the section above.
Finding IDocs with certain functional Errors
For example 1 you like to check your delivery IDocs against functional errors for which you are responsible for.
Those failures are identified by the following status message settings:
- Status Message Qualifier: SAP
- Status Message ID: ME
- Status Message Number: 777
Once the IDoc runs into such an error further matching status records are created at the same time which, however, does not reflect the initial error situation.
Thus you set the “Relevant Status Record” = “First status record with matching status”.
So only the first occurrence of all matching status records is checked against the settings in status message parameters, and hence will only find the IDocs relevant for you:
The following example 2 shows a similar use-case. Inbound order IDocs shall be monitored and alerted if they run into a functional error:
- Status Message Qualifier: SAP
- Status Message ID: VG
- Status Message Number: 204
In this case, each time such a functional error occurs, preceding status records with same status number are written which again are not of interest as they cannot be used to determine the responsible person to be notified about the IDoc failure. Thus, in this case the last matching status record shall be compared with the status message parameters, so parameter “Relevant Status Record” is set to option “Last (current) status record”.
Imagine the IDocs of above example 2 are subject to automatic reprocessing which might create further erroneous status records which are however not usable for identifying the underlying functional error. Thus you are always interested in only the third status message created:
In this case you can use the following settings in monitoring setup:
- Status Message Qualifer: SAP
- Status Message ID: VG
- Status Message Number: 204
- Status Counter: 3
- Relevant Status Record: First status record with matching status considering Status Counter
This will always evaluate the third matching status record (which is known to be the relevant one) against the status message parameter settings.
Set up “IDoc (Analysis)” for Reporting Purposes
One of the features these reporting tools offer is the display of data in an aggregated way. To facilitate this display the data collector is able to group the measured values by parameters "Partner Number", "Message Type", “Segment Field Value 1”, “Segment Field Value 2”, "Status", “Status Message ID”, and “Status Message Number”.
In order to activate this aggregation the "Group by" flag has to be set for each of the parameters in scope. You can either provide a set of entries you want the data collection to be restricted to (e.g. you are only interested in a small sub-set of partner numbers), or you can leave the corresponding fields blank which means all possible values found on the managed system will be included into the aggregation (e.g. aggregate all message types found for the specified IDoc interface).
If you want to group parameter "Status No." on metric level, you have to set the "Group by" flag and additionally enter a wildcard character into the select-options field. The aggregation for parameter “Status No.” can only be performed for the count and percentage metrics.
