6 Documenting BPM Projects
Oracle Business Process Composer processes documentation from the project-level, process-level, and activity-level. None of the documentation fields are mandatory; you can use any, some, or none of the fields.
6.1 Understanding Project-Level Documentation
Both project and role descriptions are available at the project level.
A project description is one or two sentences that help a user distinguish between projects of similar or same titles. A role may require more explanation as it can be an acronym that is not commonly used.
6.1.1 Project Description
A project description is one or two sentences that help a user distinguish between projects of similar or same titles.
Description Location
-
When a project is created, as shown in Figure 6-1.
-
Within a project, click on More Information to add, edit, or delete the description, as shown in Figure 6-2.
When Used
When a user displays all projects available in all spaces, one or more projects of the same title may be displayed. In a multi-national corporation, there might be several Operations projects for different countries or divisions. The project description helps the user choose the appropriate project to open.
Where Used
Detailed Business Process Report
The project description also provides the appropriate context for a report on a project. Reports are often saved and distributed to viewers who do not have access to Oracle Business Process Composer, therefore it is important to provide detailed information on the project for which the report was created.
6.1.2 Role Description
A role may require more explanation as it can be an acronym that is not commonly used.
Description Location
Within the Narrative View below the role. You can add, edit, or delete the description.
When Used
The role description is used when a role requires more explanation.
Where Used
Detailed Business Process Report - Participants Table, as shown in Figure 6-3.
Figure 6-3 Detailed Business Process Report - Participants
Description of "Figure 6-3 Detailed Business Process Report - Participants"
6.2 Understanding Process-Level Documentation
Several kinds of documentation are available at the process level, including descriptions, links, requirements, and notes.
The following process-level documentation is available:
-
Process description
-
Process documentation
-
Process links
-
Requirements
-
Process notes
6.2.1 Process Description
Like the project description, the process description is a one or two sentence expansion of the title. The description helps make a clear distinction between processes with similar titles.
Description Location
-
When a process is created, as shown in Figure 6-4.
-
In the General tab of the Business Properties pane, as shown in Figure 6-5.
-
Below the process name in the narrative view, as shown in Figure 6-6.
When Used
The process description can be added or changed in several places, such as during process creation, in the business properties property panel, and in the narrative view.
Where Used
-
Detailed Business Process report
-
Business Requirements report
-
Process Properties report
In a report that contains many processes, the process description can help the reader quickly navigate to the correct process. The description can not only explain what the process covers, but it can also detail what it does not cover along with a pointer to another process.
6.2.2 Process Documentation
Process documentation is rich text documentation that can be added to a process in the narrative view or in the documentation panel. If the documentation exists elsewhere, the user should add links so that information is not duplicated. If the documentation is more helpful in the activity documentation or description fields, it should be added to the field that is the most useful to the user.
Please note the Documentation Type option, which is displayed at the top right-hand side of the Documentation tab, as shown Figure 6-8. Use the drop-down list to choose if you want your documentation to be created for external (End User) or Internal use. For your documentation to appear in the narrative view or process reports, you must set this option to End User. If the user doesn't realize that it is set to Internal, they may be confused when they don't see their documentation.
Documentation Location
-
Below the process description in the narrative view, as shown in Figure 6-7.
-
In the documentation tab of the property pane, as shown in Figure 6-8.
Figure 6-8 Process Property - Documentation
Description of "Figure 6-8 Process Property - Documentation"
When Used
Documentation is added to a process when the information is important for comprehension or following the process, or when the information does not exist elsewhere.
Where Used
-
Detailed Business Process report
-
Business Requirements report
6.2.3 Process Links
If the name of the link is generic or could be confused for another document, use the description to provide more detail. For example, if there are several checklists that are used by the sales organization, the description can help the user determine if the link is to the appropriate checklist.
Links Location
In the Links tab within the business properties, as shown in Figure 6-9.
Figure 6-9 Process: Business Properties - Links
Description of "Figure 6-9 Process: Business Properties - Links"
When Used
Links can be added to activities, processes, requirements, activity documentation, and process documentation. The description should be short and expand on the title to help a user determine whether the link contains the appropriate document.
Where Used
-
Detailed Business Process report
-
Business Requirements report
6.2.4 Requirements
Requirements can be added to a process in the business properties. There are two plain text fields - notes and solution - where more explanation can be added. Links to existing documentation can also be added.
Description Location
In the Requirements tab within the business properties, as shown in Figure 6-10.
Figure 6-10 Process: Business Properties - Requirements
Description of "Figure 6-10 Process: Business Properties - Requirements"
When Used
The requirements feature tracks the status, priority, and difficulty of the requirements of a process. Multiple requirements can be added to a process and they can be sorted by the various components, such as date, status, and so on.
Where Used
-
Detailed Business Process report
-
Business Requirements report
6.2.5 Process Note
A process note is the equivalent of a sticky note - impermanent and to be used more as a reminder. They are deleted as soon as the information is used.
Note Location
In the graphical view, a note can be dragged from the palette to the process, as shown in Figure 6-11.
When Used
Notes are useful when collaborating with others while creating or editing a process. They are highly visible and can be easily added and deleted.
Where Used
Notes do not appear in the narrative view or in process reports.
6.3 Understanding Activity-Level Documentation
Documentation available at the activity level includes descriptions, links, comments, and notes.
The following activity-level documentation is available:
-
Activity description
-
Activity links
-
Activity documentation
-
Activity comments
-
Activity notes
-
General
-
Issues
-
RACI (responsible, accountable, consulted, informed)
6.3.1 Activity Description
The activity description should be a brief expansion of the activity name.
Description Location
The activity description is located in the following areas:
-
Graphical view, in the properties of an activity, as shown in Figure 6-12.
Figure 6-12 Activity Description (Graphical View)
Description of "Figure 6-12 Activity Description (Graphical View)" -
Narrative view, below the activity name, as shown in Figure 6-13.
Figure 6-13 Activity Description (Narrative View)
Description of "Figure 6-13 Activity Description (Narrative View)"
When Used
Names of activities tend to be very short. The description is an expansion of the name to help with understanding.
Where Used
-
Detailed Business Process report
-
Business Requirements report
-
Human Tasks vs Process report
-
Services vs Process report
6.3.2 Activity Links
Links can be added to activities, processes, requirements, activity documentation, and process documentation. The description should be short and expand on the title to help a user determine whether the link contains the appropriate document.
Links Location
In the Links tab within the business properties, as shown in Figure 6-14.
When Used
Customers often have a rich store of existing documentation that can be referenced from the process. Multiple links can be added to an activity, and these links are active in the process reports.
Where Used
-
Detailed Business Process report
-
Business Requirements report
6.3.3 Activity Documentation
Activity documentation is rich text documentation that can be added to an activity in the narrative view or in the documentation panel. If the documentation exists elsewhere, the user should add links so that information is not duplicated. If the documentation is more explanatory elsewhere, for example, in the description fields or as a comment, it should be added there. In other words, add it to the place that is most useful to the user.
Please note the Documentation Type option, which is displayed at the top right-hand side of the Documentation tab, as shown Figure 6-8. Use the drop-down list to choose if you want your documentation to be created for external (End User) or Internal use. For your documentation to appear in the narrative view or process reports, you must set this option to End User. If the user doesn't realize that it is set to Internal, they may be confused when they don't see their documentation.
Documentation Location
The activity documentation is located in the following areas:
-
Documentation tab of the property panel, as shown in Figure 6-15.
Figure 6-15 Properties Panel: Documentation - Activity Documentation
Description of "Figure 6-15 Properties Panel: Documentation - Activity Documentation " -
Narrative view when the activity is in focus, as shown in Figure 6-16.
Figure 6-16 Activity Documentation (Narrative View)
Description of "Figure 6-16 Activity Documentation (Narrative View)"
When Used
Documentation should be added to an activity when the information is important for comprehension or following the process, or the information does not exist elsewhere.
Where Used
-
Detailed Business Process report
-
Business Requirements report
6.3.4 Activity Comments
Activity comments can be added to an activity through the business properties. After it is added, a comment cannot be edited or deleted.
Comments Location
In the Comments tab within the Business Properties panel, as shown in Figure 6-17.
When Used
Activity comments are like notes in that they are brief, but, unlike notes, they are permanently attached to the process, and they are displayed in several process reports. Use comments when it is important to keep a record.
Where Used
-
Detailed Business Process report
-
Business Requirements report
-
Issues and Comments report
6.3.5 Activity Note
An activity note is the equivalent of a sticky note - impermanent and to be used more as a reminder. They are deleted as soon as the information is used.
Note Location
A note can be dragged from the palette to the activity in the graphical view, as shown in Figure 6-18.
When Used
Activity notes are useful while collaborating with others when creating or editing a process. They are highly visible and can be easily added and deleted.
Where Used
Notes do not appear in the narrative view or in process reports.
6.3.6 General
The General tab tracks the cost, organization unit, application system, and time to complete an activity.
General Location
In the General tab within the Business Properties panel, as shown in Figure 6-19.
When Used
General information is used for process improvement and discovery; it can be important to track the cost of performing the activity as well as how long it takes to complete.
Where Used
-
Detailed Business Process report
-
Business Requirements report
6.3.7 Activity Issues
The activity issues should be used to track specific issues including their severity, priority, and resolution status.
Issues Location
In the Issues tab within the Business Properties panel, as shown in Figure 6-20.
When Used
Issues can be used during process improvement, testing, and discovery; it can be important to track the issues that are discovered. The issues can be sorted by severity, priority, resolution status, and date.
Where Used
-
Detailed Business Process report
-
Business Requirements report
-
Issues and Comments report
6.3.8 RACI
The RACI feature tracks who is responsible, accountable, consulted, and informed on an activity.
RACI Location
In the RACI tab within the Business Properties panel, as shown in Figure 6-21.
When Used
The RACI data can be used during process improvement, testing, and discovery to ensure the proper roles are involved in the activity.
Where Used
RACI report