Introduction

This blog is about Solution Documentation in Solution Manager 7.2. It’s a bit critical about the functionality, but hopefully in a constructive way. It came about after I wrote an ABAP report that addressed the shortcomings as I saw them. Even if you are not using such a report, I’ve always thought that knowing in what way something is not as good at it can be helps in coping. Certainly, I found the existing reporting a limitation on adoption.

Background

In Solution Manager 7.2, Solution Documentation (SOLDOC) is the centralised repository of a company’s business processes. It contains all the essential information created during the design of business activities and stores for future reference the map of the interconnections across every application component in the business landscape.  SOLDOC provides added value in three key areas:

• A true business area hierarchy of all business processes including process steps and their actual executable activity (otherwise known as the Business Process Master List, or BPML). This hierarchy is not, as so often represented, a customer specific collection of folders; SOLDOC follows the industry standard categories from business area at level 1 through to process groups, assigned processes, steps for a process, variations and ultimately the executable performed by these steps at level 6.
• An integrated process diagram to visualize the coordination of steps and interfaces to achieve a defined business outcome (a process diagram is drawn with Business Process Modelling Notation, BPMN). Different business diagrams are possible to highlight variations in process flow if only one diagrammatic representation is insufficient.
• Additional documentation assigned at correct place, in context, to inform and enrich each process step about who, how and when it should be performed, and how the process was realised (e.g., Functional and Technical Specifications, Test Scripts etc).

Thus SOLDOC is less a document repository to collectivise information about the project and more a modelling tool in its own right, that not only models processes but also the organisation of the processes both between each other (end to end process flow) and the documentation within it.

And yet, despite being this all-encompassing single source of truth, SOLDOC reporting is generally regarded as very poor, and not up to the task of supporting a project workstream’s task list, particularly authorisation requirements based on activities assigned to  business process role. It is a very similar situation to the classic online transaction processing (OLTP) versus online analytical processing (OLAP) conflict: what is an optimal configuration for data entry is not optimal for reporting. While SOLDOC has a place for everything, and everything in its place, the extraction of the information in reality reverses the user navigation, slowing everything up and stymieing an overview picture.

Yes, there is a “list” functionality, and with good filtering functionality, but the problem is that the overlay of the BPML on a simple list report is lost in the on-screen output. Whilst export of the list to a spreadsheet is possible, unfortunately not one list output suffices to provide a combined view -leaving the user with a complex re-integration processes to figure out. As a simple example, it is not possible to create a list of Process, Process steps and all assigned executables in one simple to read report. These typical problem scenarios and our own solutions are discussed in the remainder of this blog.

Problems with existing Solution Manager Process Management reporting

List views

1. A hierarchical display of the BPML and component libraries, and an interactive drill-down to lower levels represented by infinitely rightward growing columns, with assignments and attributes in adjacent windows.
2. General global searching across the entire project phase view (known as a Branch), and a specific where-used search for an object.
3. List reporting of the hierarchy with reference to the hierarchy path the found object resides.
4. Exporting of the list report to a spreadsheet.

1. Select on Folder.
2. Select on Scenario.
3. Selection on Business Process.
4. Selection on Business Process Step.
5. Highlight executable assignment the step.
6. Open tab for all elements assigned to the selected executable.
7. Open tab for all elements assigned to, e.g., the configuration unit assigned to the selected executable.
8. Open tab for all elements assigned role to configuration unit.
9. Check values in the in the attribute widow.

So, everything is available and reachable, but often seems to need a burdensome number of clicks to access the information.

A second issue is that of a lack of context for the hierarchy in a list, in that only a hyper-text path link is available for each object found. The Hobson’s choice for a user is viewing either just one element in its hierarchical context, or listing all elements divorced from the hierarchy it belongs to, save for a hyperlink to the hierarchical view.

Fig 2. Example list report showing hierarchical path column

Thirdly, the list reporting will not output multiple executables for a step. From a BPML standard viewpoint, this could be argued as not a real problem, because each step should have one exclusive executable assigned. In practice though, if a controller role requires access to a range of reports to perform a check step, the BPMN diagram rules requires a clunky representation of a sub-process of unconnected steps (the official BPMN representation of ad-hoc) which alternatively could be neatly shown as the unofficial multiple assignments to a step. In most cases, business blueprints represent this scenario as multiple executables, not the BPMN semantically correct ad-hoc process step representation, not least because all the information to understand the step would be only discoverable from process diagram inspection.

Lastly, and more generally, the list view does not show assignments or their attributes. To create such a report requires downloading separate reports into excel and advanced Excel commands to create a useable report.

Roles

Roles have two meanings in SOLDOC. In the process diagram, under BPMN semantics, a role can be represented by a swimlane. However, for building authorisation profiles, relying on the swimlane is never a good option. This is because under BPMN the swim lane is merely a way of dividing up a diagram and is loosely defined. It can be a role, or a position, a team or a department – or even a system, although SOLDOC handles system swimlanes as a special case. Mapping organisational units to named individuals is always going to be a problem unless group membership is maintained outside of SOLDOC.

However the role is defined,  under BPMN it is merely a descriptive identifier and can change based on context. In one diagram it can be Accounts Payable accountant, in another diagram the same role is called A/P accounts, and a third just Accounts.  Easy to assume they all mean the same thing, until they do not.  While a list of such diagram entities is stored centrally, and encourages re-use, ultimately not having a clear single identifier beyond a free text description field is always going to cause problems – despite the new merge functionality.

Fig 3: Diagram role list

To solve the problem of an ill-defined swimlane role for a process step in the diagram, there is available for assignment to a business process step an object called an ‘End User Role’. This role comes from the 25-year-old HR-Org module in R/3. It was originally included in the earlier 7.1 version Solution Manager “Business Blueprinting”, to allow filtering of training material by user groups for whom certain topics are relevant in a Learning Map. As standard, the End User role can reference one of the three object types:  user, position, and department, but others object types such as job can be configured for selection. Further details on End User Roles can be found here.

Learning Maps no longer exist in the new 7.2 version of Solution Manager “Process Management”, but the value of End User roles exists in providing a role unique identifier to a business process step, in a consistent and reportable way that swimlanes as diagram entities do not.

Business Process Variants

A business process variant is an alternative process flow for a business process. It sits below the level 3 process and contains a set of the business process steps defined in level 5, and in effect is no more than an alternative process diagram at its own level. There can be several alternative variants for a business process step, or even none. Of course, instead of a level 4 variant alternative process flows can always be catered for with additional gateways (e.g., XOR the exclusive either/or condition) but the variants formalise these different paths as a separate entity.

A typical use case for creating  a process variant is when the data mandates alternative steps, the classic example being the handling of dangerous goods. Such a case would typically involve a slight modification to the process, but not one requiring an entirely separate process, nor an alternative processing that should be buried in the details of an extended diagram.

Currently there is no way in the BPML to identify which steps are exclusive to a business process variant as the process diagram needs to be inspected for these to be identified. Business process steps may also be shared across some but not all variants. The authorisations for these steps would be different per variant for both the role in the process diagram or the data driving the alternative processing.

Such omissions, particularly in terms of the ease in which this data can be consumed, can become a severe barrier to adoption of the SolDoc functionality. This is especially true for hard pressed project teams who already see the simple task of documentation, let alone using Solution Manager, as a barrier to getting their work done. As such it is important to overcome these challenges to ensure that the best possible use is made of SolDoc, allowing it to realise its potential as a valuable asset for project delivery and ongoing BAU. In the next section we discuss how  these challenges were addressed on a recent project and how, through a custom report, the consumption of the SolDoc data was vastly simplified.

A new SolDoc reporting solution.

Many project customers have requested for some way to take this information out of a pictorial representation of a BPMN process diagram and enrich the description of attributes and assignments of a shared process step in a searchable and usable way. It is precisely this requirement that is addressed in the new SOLDOC reporting tool.

Branch selection and filtering

The report is run online and reads an entire branch in a couple of minutes. A solution and a branch need to be selected at a minimum.

From there, the output can be filtered for logical component groups, executables name, authorisation role (if assigned to an executable) and any End User roles.

Fig 4: Report selection screen

Additional selection to add interfaces for a business process to the report output is available. It is also possible to restrict executables shown to only Fiori Apps.

Configuration units assigned to steps are also reported. This is the solution we use for adding variant relevant master data to indicate allocated steps to variants outside of the BPMN process diagram: The config unit type need not be master data, but in the selection screen example above it is type MADA (Master Data) with

• the single value field maintained in the reference config unit assigned to the business process step taking the variant name, and
• the multi-value fields maintained in the Configuration Library for the original config unit object containing the master data.

A use case would be to create sets of document types or order statuses in the Config Library, and allocate these entity sets to steps corresponding to the business process variant they would be used in the BPML. Below is a conceptual overview of the expected assignment of elements:

Fig 5: Overview of element relationships

There are two displays: and ALV tree view, and an ALV grid view (the grid view is also displayable in an Excel spreadsheet).

Fig 6: ALV tree output

• The ALV tree output reports each level 1 (Business Area) as a blue triangle icon with only hierarchies resolving in an executable being displayed. Any step that does not have a level 6 activity will not appear in the output. The scope of this report is to document role to step assignments for authorization builds and not serve as a validation report to check that all entries have been maintained correctly.

• Variants are listed in the tree structure only, as they add context for the business process. As was mentioned before, level 4 business process variants are an optional level and do no group level 5 business process steps.

• Multiple executable assignments can easily be shown in the tree structure, as well as assignment of multiple end user roles, for when a step can appear in two swimlanes. Also not shown are any interfaces (which would include sending and receiving LCG in the columns) and authorization roles assigned to executables.

• Additional information is added to the right of the tree structure in the columns area. For example, the LCG that a process step belongs to indicated, the action of a Fiori App, or the entity for the that configuration set, in this case the applicable business process variant. And standard ALV functionality allows the order of these columns to be dragged and dropped to make easier reading across the tree node.

As an alternative to the tree output view, and switchable between each other, is the grid display output. The sample output shown below is from the tree view. It has been sorted to make it easier to read, so every row does not have a repeated entry, but all information from Level 1 to Level 6 is included in one row. Also included in additional rows are roles assigned to a step, authorisation for the executable, and config units with master data for a particular variant. Sorting makes information available in one row, without the need for earlier mention navigation, or excel spreadsheet combining.

Fig 7. ALV grid output

And of course, no report would be complete without still providing the ability to export the data to an Excel spreadsheet for further filtering and sorting as required.

Conclusion

In summary, the poor SOLDOC reporting can be listed as:

• List functionality to see everything at once loses BPML hierarchy information.
• Too many clicks are required to retrieve information between BPML hierarchy, process diagram elements, library elements and assignments.
• Showing multiple executables for a step is clunkily enacted in the BPMN standard and the easy alternative is not reportable.
• Capturing the business rules for process variants and step allocation is missing.
• Roles inside BPMN diagrams are not visible in any listing, and imprecisely defined.

These issues damage adoption of the SOLDOC application, but a new report is needed to address all these concerns. Other report options exist, such as validation of entries and interface catalogue reporting integrating the Interface Documentation assignment into interface elements into the same level as the basic list output.

If you’ve also experienced difficulty gaining adoption of SolDoc due to the issues highlighted here or would like to find more about this reporting, then feel free to discuss in the comments.