SAP CPM, MRS, AIF

Interface between SAP Commercial Project Management (CPM) and SAP Multi Resource Scheduling (MRS) using AIF - Application Interface Framework

Introduction:

This document is only for experienced consultants and not for beginners. To understand this document, one should know basic concept and understanding of SAP Commercial Project Management(CPM), SAP Multi Resource Scheduling (MRS) and SAP Application Interface Framework (AIF). The SAP Application Interface Framework (AIF)enables you to develop and monitor interfaces as well as execute error handling in a single framework residing in your SAP back end system. AIF have user-friendly transactions for interface monitoring, error handling, and the correction of errors directly from within the application system.

There are many interface points between SAP CPM and SAP MRS or third party resource management tool (therefore I use the word 'Interface' in this document). The main interface point between SAP CPM and SAP MRS is the staffing process. CPM sends demand information to MRS and MRS sends the staffing information back to CPM. In a professional services scenario, the financial planning for a project using CPM workbook is done by a Project Manager/Controller (PjM) and staffing of resources & assignments in MRS are done by Resource Manager (RM). Moreover, in most of the clients, both personnel will be working in the same time zone and timing.

During assignments postings from MRS, the Resource Manager often encounters a common error 'Workbook is locked by user 'XXXXXX''. This document talks about this error and how to handle this error.  

You may be thinking, what is the big deal. Push the MRS assignments to CPM once the workbook lock is released in CPM. Yes, you are right. The Resource Manager must wait for the release of the workbook lock.

1.      How much time should the RM wait?

2.      How does the RM know that the workbook lock is released?

3.      If Synchronous call, during this lock time, RM cannot save her/his work on the locked projects. What is the resolution?

4.      If Asynchronous call, RM hard booked the resources in MRS and CPM does not know about this. How to reconcile this discrepancy?

5.      During workbook locked duration, how does one handle the multiple change/update for a same assignment?

 
For example, RM has a task of staffing resources for two different projects for a day. Both the projects are locked by the PjM by keeping the workbook open for change of planning or forecasting. In most of the Professional Services Clients, Planning and Forecast workbooks will be in the same infocube. If either one of the workbooks is open; the infocube will be locked.   

This would totally hamper the daily duties and work of any resource manager. For the RM to continue his/her duties with less hurdles, we need to find a solution in SAP and it's AIF.  

Come. I will take you through this journey.

 Possible Scenarios of Workbook locking:

There are many possible scenarios where workbook locking can happen.

1.      The Project Manager is working on the CPM workbook and the Resource Manager is working on assignments in MRS for same project and same time.

Project Manager is working on either planning or forecasting workbook and Resource Manager is working on assignments/staffing and push data into SAP CPM and this happen at the same time. This will result in CPM workbook lock, and the Resource Manager will get error message that CPM workbook is locked by Project Manager.

2.      In Analysis Office (AO), the Project Manager accidentally closes the workbook by select the close icon “X” in the upper right corner of Excel.

If the PjM has changed any data, AO will force a message to save the data.  If the PjM bypasses the message, data would be lost. There is no workbook locking in this case, and this is sufficiently addressed in the standard handling. But there is a possibility of workbook lock. 

3.      Excel Crashes or Windows / Laptop Crashes

The SAP session manager interprets this as a disconnect and releases the AO locks; any data not yet saved is lost.

Updates made to the AO user buffer will be lost, but this is not due to an AO specific error; this is the standard design.

The AO could also be negatively impacted if the Excel process is not closed during the crash or is part of the recovery. Various AO errors have been encountered in this situation, such as the AO opening but not returning any data. There is a possibility of workbook locking here.

Restarting Excel will bring the AO back to a consistent state but cannot guarantee the workbook lock release. 

4.      Project Manager leaves the AO session unattended for a period exceeding the production session time-out limit.  No changes to the AO data were made.

In standard SAP, the production session time-out limit will be 15 minutes; we can configure this. If the workbook is inactive for a certain period of time, the system will automatically release the locks and the session will be disconnected.

Till production session time-out, the RM cannot post assignments to CPM. The Project Manager will receive a BI disconnected error if he/she attempt to resume processing with the same session. After the disconnect, the PjM needs to refresh the session to continue.

5.      The Project Manager leaves the AO session unattended for a period exceeding the production session time-out limit.  AO data was changed.

The session is disconnected, the locks are released.

Updates made to the AO data in the user buffer will be lost, but this is not due to an AO specific error; this is the standard design.

The Project Manager receives a BI disconnected error if she/he attempt to resume processing with the same session after the disconnect. The Project Manager needs to refresh the session to continue. The Project Manager will have to reenter his/her updates.

Solution

When the Resource Manager tries to update the assignments in CPM from MRS, he/she should get a warning message, 'Workbook is locked by Project Manager. We will update the assignments after unlock.'

This would remove the burden of the Resource Manager to worry about assignment updates in CPM and will continue their job in MRS.

How to achieve this solution?

When the data comes into CPM and we find that the workbook is locked, then this data from MRS should be passed to AIF. But in the front end screen of MRS we will show warning message ' Workbook is locked by Project Manager. We will update the assignments after unlock'

What will happen once the error message and data is passed to AIF?  

The following functions will happen.

1.      Error Logging

2.      Sequencing

3.      Automatic Reprocess

4.      Automatic notifications

AIF will log the messages, sequence the messages and reprocess automatically and periodically. Once the workbook is closed or the  lock is released, then the updates to the workbook will happen automatically and send notification to RM or MRS or to other systems that this work is completed.

This can be achieved by configuration in AIF and using ABAP program.

Error Logging. 

First, we must decide,

1.      Are we going to log all types of messages into AIF including success and errors?

2.      Are we going to log only Error messages?

3.      Are we going to log only certain error message?

AIF can handle all the above questions. A subroutine to be written in the BAPI which we use for interface between CPM and MRS. Based on the requirements, we can bring different types of messages into AIF. A raw data structure containing all the import and export parameters of the inbound/outbound function module should be created. You can generate this structure using transaction '/AIF/WET_GEN '  and additional fields can be added to the structure as per requirements.

Pass these information into the structure which we have created. If the incoming data structure and the Raw data structure are different, we can map the fields using AIF configuration in structure mappings, value mappings, fixed values, checks. Moreover, we can use BRF+ for rules and conversion to map the values. To achieve this, in configuration, you have to specify the BRF+ Application and BRF+ function.

My recommendation, log all types of messages either successes or errors in AIF. If you want to log only certain types of errors like locking errors only, you will be forced into a complicated scenario that I have described in the summary of this document.  Even though we log all types of messages, we can specify which type of errors to be reprocessed automatically. This would help data errors to be reprocessed manually in AIF and no action on success messages.

 

Sequencing

Serialization ensures that the messages are processed in the right order within the SAP Application Interface Framework. A message that relates to the same assignment should not be processed in case its predecessor has not been processed yet. Also, messages related to different assignments or projects should not have to wait for each other.

You may be wondering why we need serialization of messages.

For example:

Step one: The RM assigns a resource for 16 hours. A message is sent to SAP to update the staffing information in CPM, but the workbook is locked because the PjM is working on the workbook. Therefore the RM will get a warning message, 'Workbook is locked by Project Manager. We will update the assignments after unlock.'

Step two: The RM sees that there is an error in the assignment and changes the assignment.

Step three: The RM changes the assignment to 160 hours. The PjM is still working on the workbook.

If all of this happens within a few minutes and the SAP CPM workbook was locked during this entire time, we should ensure that the updates happen in the correct sequence after the workbook is unlocked. Otherwise, the latest update would be 16 hours instead of 160 hours.

Alternatively, we can use qRFC for sequencing the messages. But the simplest way is to use AIF serialization configuration for sequencing the multiple updates for one assignment.

If you try to post the same assignments more than once, you will get a message 'A predecessor exists for the assignment' and the message will be in queue for automatic reprocess.

Automatic Reprocess periodically

 Manual reprocessing will not guarantee sequencing of messages; therefore, manual processing should not be allowed for CPM workbook lock errors.

During reprocessing workbook lock errors, it may result in data errors. Configure alerts in AIF for data errors and send a notification to business user so that a manual reprocess can be done for data errors.

You need to create an action and assign in transaction /AIF/REP_AC_ASGN  for Assign Reprocessing action. Here, you should mention how many times you want to process the message (counter) and in what frequency. The screen shot below shows 5 minutes frequency for 12 counters.

The system will schedule a reprocessing batch job automatically for every 5 minutes in the background. If the message is processed successfully, then the counter stops and no more background batch job is scheduled. 

Automatic notifications

There are two types of notifications in our scenario.

1.      Notify business users or notify MRS system or another partner system for all types of messages or only error messages or certain type of error messages.

2.      When the counter for reprocess completed and still in error, notify Resource Manager.

If you want business user/ RM to receive the notification, we can configure alerts in AIF. If you want MRS system or other partner system to receive a notification you need to have a notification process out of AIF. You can use the existing BADI for triggering events and notification during save in the infocube.

There is no standard way in AIF for notifying RM when the counter for reprocess is completed and still results in error. You need to create a Ztable and update the counter log. Compare the AIF counter with the counter in the  Ztable counter every time when you process the message. When the counter is completed and still results in error, trigger an event and send a notification to RM. 

 

Summary:

During assignments postings from MRS, the Resource Manager often encounters a common error 'Workbook is locked by user 'XXXXXX''. The RM does not need to wait for the release of workbook lock. The system will log the error message in AIF sequentially, reprocess automatically and notify RM on the status of the update. Based on this notification, MRS or other systems can take action and update MRS assignment status.

I have mentioned only a few functionalities/configuration in this document. For authorization, we can configure alerts and their assignment to recipients, which will ultimately define which messages the user will be able to see in the Interface Monitor transaction /AIF/err

To end this document, I have given below the reason why we should use AIF for all types of success and error messages. Assume that the reprocessing frequency is 15 minutes.

1^st  Minute: The PjM is working on the workbook and the RM tries to post an assignment # 987654 for a qty of 16 hours. (we call update 1). Error message is logged in AIF and it is waiting for reprocessing to happen automatically.

5^th Minute: The PjM closes the workbook and the workbook lock is released.

10^th Minute: The RM change the qty to 160 for the assignment # 987654  and saved the assignment (We call update 2) . Since the workbook is not locked, 'update 2' will be successful.

15^th Minute: Reprocess kick start and update 1 will happen in the workbook.

In the above scenario, the latest updated staffed qty in the workbook is 16 and not 160. This leads to a  serious discrepancy.

To avoid misalignment of sequencing and reprocessing, SAP needs to check if another posting of the same assignment exists in AIF while posting any assignment to CPM workbook. If yes, then the subsequent posting for the same assignment has to be moved to AIF too. Alternatively, make a process to log all types of messages in AIF.

In other words, make AIF as one stop for all your interfaces.

I.bleed.SAP