Solution Manager provides the functionality of Solution Documentation where all the documentation related to the Business Processes as well as the new developments can be stored and maintained to keep the repository upto date. The documentation can be created using a Project or a Solution. However there are multiple tabs where different types of documents can be stored and also the behavior of the documents and its management are different in Project and Solution. Thus it’s very important to understand the basics of document governance and also the various features available for document management in Project and Solution so as to be able to decide on the document management strategy.
The main objective of this document is to illustrate the document management concepts in Solution Manager and explain the terminology related to Solution Documentation. How the different types of documents can be maintained and to understand the difference in the behavior of the documents in a Project and Solution. The reader of this white paper should be able to decide his documentation strategy after referring this paper.
3. Solution Documentation Terminology
The following are the key terms related to Solution Manager documentation.
- Technical Documentation: This terms refers to all the assignments in the form of transaction codes, programs etc. which are done to the 3-level business processes. This is always upto date as they are physically present in the managed system.
- Documents: The actual documents in MS word, powerpoint, excel files etc which describes a business process or any developments done related to the business processes.
- LOIO (Logical Representation): It’s the unique ID created whenever a document is created or uploaded in Solution Manager.
- PHIO (Physical Representation):Whenever any document or its attributes are changed a PHIO is created for it. A different ID for each version and it can be seen in the “History” tab of document attribute.
- Knowledge Warehouse (KW): It is a place where all the documents which are created or uploaded in Solution Manager are stored. A new folder is created for each Project / Solution which is created in Solution Manager.
- KW Enhancement: It is a group of folders contained in the KW. By default whenever a Project is created its folder is created in KW enhancement KWCUST release 620. A document kept in one folder can be referenced (linked) from another folder (Project) within the same KW Enhancement and can be changed from the original or the referenced location.
- Late Copy: When a document in one KW enhancement is linked to a Project created in a different KW enhancement then the document will be exclusively changeable from the original folder. When the document is changed from the linked place the system creates a copy of the document in the other KW enhancement folder. This is known as late copy.
- Document Attribute: It’s a combination of attribute (customer defined) and its value which can be assigned to the documents for filtering purpose. E.g. Attribute as the “Sales organization” and its value as the name of the sales organization.
- Keyword: Keyword is similar to attribute but it does not have a value assigned to it. It’s just a label which is used for filtering the documents. E.g. keywords describing the modules SD, MM, FI etc.
- Persistent Area: This describes the area which have the current productive information like the Business Process step specifications, transactions, programs etc.
- Temporary Area: All the documentation available in this area is only for a temporary period like in Major Release Project. At the end of the project all the content and documents are to be transferred to the persistent area / main project.
4. Document Type and Status Schema
There are many standard document types availablein Solution Manager and new custom specific document types can also be created. Document types can be used to establish standardization in the documents of Solution Manager. A separate document type can be created for each type of document like for Business Process descriptions, test cases, technical specifications etc. A customer specific document template can be uploaded for each document type so when a new document for that type is created a pre-defined format opens.
Document Status Schema:
Standard status schema is available but customized status schemes can also be created and assigned to specific document types. The end status should be such that it locks the document so that it can be prevented from unauthorized changes. It is also recommended to have a common end status in all the status schemes.
5. Project as Single Source of Truth
Single source of truth means a place where all the information in available as it is being used productively and can be accessed at any point of time. Using Project as a single source or truth means the Solution Manager Project will be considered as the central place for the documentation purpose and all the productive information will be available in that Project. All the documents can be maintained in the different tabs available like General Documentation, Project Documentation, Configuration, Development, Test Cases and Training Materials Tab. During the initial blueprinting phase all the documents are created and maintained in the main Project. Once all the Business Processes and documentation is finalized then for all the major changes a Major Release Project is created. The documentation present in the Major Release Project are in the temporary area and are transferred to the persistent area once it’s the Major Release Project is over.
Document Management during maintenance:
All document can be created, changed and stored directly in Solution Manager. To lock a document it can be checked out and saved on the user’s machine to carry out the changes. The checked out document will be available to other users only in the display mode. After making the changes the document can be checked in and subsequently the SolMan document will be updated.
Except for checking out a document the only other way to control the changes to the document is by restricting the authorization of the particular node. Specific users can be assigned to the nodes and only they will be able to change the document. If no such restriction are in place then any user who has the change authorization for that Project can make any changes in any document assigned to the Business Process structure.
If the history logging is enabled then in the attributes of the documents, in the “History” tab all the changes which will be logged along with the name of the user who has done the changes and also the previous versions will be available in Solution Manager and can be accessed via the “History” tab.
Document Management during Major Release / Roll Out Project:
Whenever a major change is needed in the Business Process structure a Major Release Project is created. A part of Business Process structure like a Scenario can be copied to a Major Release / Roll out project and thus the same document is accessed concurrently from 2 locations. To make the changes clear it is recommended to make the changes related to the major release / roll out project in different chapters within the document.
Test document is an exception as the major release project can have different test case so the original test document might not be changed. All the changes should be approved at the end of the maintenance / implementation phase and then moved to the persistent area. The document can also be linked so the same document can be accessed from multiple locations and updated simultaneously from different places. An example of such a shared documentation could be a development or configuration documentation for user exits or BAdIs used for several different business processes/steps.
The document can also be locked for changes using the status “Release” or the final status of the custom status schema and the status can be changed for updating the document with proper approvals. Document Attributes and Keywords can be used to filter and report the documents. Additional KW folder can also be used to restrict the access to certain group of users by limiting the authorizations. A different folder can be created and the confidential documents can be kept in that folder so only a limited user group can access it. For the Business Process structure management it is recommended to use the structure attributes on the Administration Tab to maintain the processing status like “ready for test”, also team members can be assigned to the processes or steps to restrict the authorization and other users who are not assigned to the nodes will have access in display mode only.
This use case is most suitable for Test management as new and old test information is available in one place and integration and regression test plans can be created and maintained very quickly. A strong Quality Gate control should be established to guarantee consistent quality and permanent update during roll out/release/maintenance activities. Business process ownership should be established to assign responsibility to approve and control changes within the business process documentation.
6. Template Project as Single Source of Truth
A Template Project can also be used as a single source of truth in SAP Solution Manager. The Template Project can be used in 2 ways to manage the Business Processes.
Use of Templates:
- All the business scenarios along with the documentation are maintained in the Template Project and each business scenario is given a Template ID.
- The templates can then be assigned to the Major Release / Roll out Project by selecting the template in the scope tab in the project data.
- By assigning the template all the Business Scenarios and Processes are transferred to the Roll out project along with the documentation and the assigned objects.
Without use of Templates:
In case no Template ID has been created then the Business Scenarios and Processes can be flexibly selected and assigned to the Roll out Project
Document Management in Template Project as Single Source of Truth
- General Documentation: The document in this tab provides general description about the business scenario and business process and are transferred to the Roll out Projects but are cannot be directly changed from there.
- Project Documentation: In the Template Project this tab is used for the internal purpose and the document of this tab are not transferred to the Roll out project. In the Roll out / Major Release Project his tab is used for the region / country specific information and if required this information can be brought into the Template Project via compare adjust. The other documentation tabs behave in the same manner as in the Implementation Projects. The behavior of copy addition and replacement of the original document is the same as in the Implementation Project.
Document Management during maintenance:
The document can be directly changed in the project for maintenance. To lock the document it can be checked out to the local desktop so that other users can only access it in display mode. The document management during maintenance is similar to the one in Implementation Project.
Document Management during Major Release / Roll out Project:
The document management during major release project can be made to follow the concept of Late copy by creating the Roll out projects in different KW Enhancement.
The only exceptions are the documents stored in the General Documentation tab (which cannot be changed in the Major Release Project) and the documents in the Reference Folder which can be directly changed from the Major Release Project without creating a late copy of it.
The document marked as blueprint relevant in the General Documentation tab will automatically get copied in the Project Documentation tab in the Roll out project. These documents can then be changed to accommodate the local business processes.
Once the document has been updated it can be brought back to the Template Project by doing a compare and adjust (only by running the project comparison report, not directly at the individual nodes).
7. Solution as a Single Source of Truth
Using Solution as single source of truth help you to have more controlled changes by using the check out / check in feature. It can be combined with ChaRM to make urgent and normal changes and for major planned changes a new Major Release Project can be created.
Document Management during Maintenance:
With the use of check out / check in changed can be done in a controlled way by assigning a Maintenance Project to it. The checked out document can be opened in the Maintenance Project and after making the required changes it can be checked in back to the Solution. If it is coupled with ChaRM then it can be made to follow the urgent and normal correction cycles.
During the check-out process the document remains unchanged in the Solution where as a new version of it is created in the Maintenance Project and once the changed document is checked in the Solution the older version is replaced by the new version and Maintenance Project again becomes empty.
Document Management during Major Release Project:
During the Major Release Project the concept of late copy (using different KW enhancement folder) is used where the documents are originally linked and then if required a copy of it is created in the Major Release Project.
In late copy there are two type of behaviors:
- Copy and addition: This type of behavior is only restricted to the test case tab. Wherever a linked document in changed the original link remains as it is and a new copy of it is created and placed below the link.
- Original document replaced by its copy: In all the tabs other than the Test Case tab the original link will be replaced by a copy of that document.
The changes in the different projects/solutions have to be identified and retrofitted into the solution and despite of the functionality like late copy and compare adjust to support this, the process gets complex and difficult with the increasing number of projects / solutions.
Since only one Maintenance Project can be assigned per Solution all the products in the landscape has to follow the same maintenance cycle, so if the software changes cannot be harmonized then the ALM architecture gets very complex.
In case of a modeling tool integration, if there are more than one projects assigned to the Solution then it becomes difficult to clearly distinguish between document management done in the project and business process changes done in the modeling tool.
The re-generation of the Test Plan is not possible from the Solution so after the test cases or the process structure has been updated a completely new test plan has to be created. Thus this use case is not recommended for customers having the strong focus on test management.
8. Document Management Recommendation:
After understanding the concepts of Solution Documentation and the various use case it can be recommended that:
- When the focus is more on test management and a central documentation is needed a Project should be selected as a single source of truth. All the documents can be created, maintained and stored at the same place. Also re-generating the test plans is easier and integration with third party testing tool is also easy. However there is a less control on the document changes and less transparency of final and in process documents.
- Template Project can be used whenever the Business Processes and its documents are varying across geographies. A Template Project with all the global processes and documents can be created and the different templates can be assigned to the different regional Roll Out Projects.
- For having more control on document changes and also to clearly distinguish between productive and planned processes Solution can be considered as a single source of truth. By integrating check out check in with ChaRM the changes of documentation can be coupled with software maintenance cycles. However this use case is not much preferred if the focus is more on Test Management.
About the Author
He is part of TCS RunSAP CoE team having expertise in SAP Solution Manager functionalities from ALM & RSlaF like Solution Documentation, SoDocA, Test Management, BPCA, BPMon, BP Analytic, JSM etc.