SERENA SOFTWARE Providing Custom Documentation for Serena Business Manager

Transcription

1 SERENA SOFTWARE Providing Custom Documentation for Serena Business Manager Pam Goodrich

2 Table of Contents Who Should Read This Paper?... 3 Addressing Unique Documentation Needs... 3 Options for Providing Custom Help and Guidance... 3 Creating Custom Process App Help... 3 Customizing the SBM User Workspace Online Help Files Serena Software

3 Types of Documentation Provided With SBM Who Should Read This Paper? This paper is intended for Serena Business Manager process app designers and administrators who want to provide help and guidance to users of the system. Options for embedding help in process apps and for and customizing the global help system for the SBM User Workspace are described, including the benefits and drawbacks of each approach. Addressing Unique Documentation Needs SBM enables you to create process apps customized to solve your unique business needs. While Serena provides documentation that explains how to install, configure, and use SBM, you may find that you need guidance tailored specifically to the processes you've designed for your business. To address this need, SBM has two methods to give help and guidance to your users or to those building and maintaining process apps. Those methods are discussed in this document. TYPES OF DOCUMENTATION PROVIDED WITH SBM Before you begin a plan to provide custom documentation for SBM, you should familiarize yourself with the provided documentation set. In general, there are two types of SBM documentation: Platform Documentation Explains how to install and configure SBM, and how to design, deploy, configure, and use process apps. You can find most of this content on the Documentation Center. Solution Documentation Describes how to install, configure, deploy, and use process apps provided by Serena. This documentation is intended for those who will implement and maintain prebuilt process apps You can download this documentation with the process apps on Serena Central. OPTIONS FOR PROVIDING CUSTOM HELP AND GUIDANCE SBM provides two options for providing custom guidance to end users: Embedding end-user help in your process app - There are several options for embedding information within your process app. This is the preferred method of providing guidance to end users because: You can provide different help for each process app. The help content is integrated and stored with each process app. As you modify your process app over time, you can easily update the documentation. Help content is preserved when you upgrade SBM. Customizing the SBM User Workspace help system - You can modify the end-user help system provided with SBM, but doing so has several drawbacks: Changes apply to all process apps in your system, so it is harder to provide process-specific help. As you upgrade SBM, the SBM User Workspace help files are moved to a backup directory and replaced with new versions. This requires you to merge your custom content into the help system every release. Creating Custom Process App Help As you work with process apps in SBM Composer, information you provide in the End-user help text setting for the following elements is displayed to users: Fields Workflows States Transitions Providing Custom Documentation for Serena Business Manager 3

4 Creating Custom Process App Help Decisions Forms The End-user help text setting is located on the General properties tab for each element. Click Edit to open an HTML editor opens, enabling you to easily format text. For applications, this setting is in the Application Editor. In this case, the description appears to users. Once you deploy your process apps, users will see the information as described in Creating Custom Process App Help [page 3]. CONSIDERATIONS FOR PROVIDING CUSTOM HELP You can use the HTML editor to link to external documents or help systems. Links are not active in hover text for fields, and transitions, but they are active on the Form and Workflow help pages. You can add help text to the End-user help text setting for each field, state, decision, transition, and workflow. If you do not provide content for a field, state, transition, or decision, the element is not listed in the help. You cannot provide custom help text for the system Update and Delete transitions; default help text is provided, however. Use the Find End-User Help Text dialog box to search for existing help content in your process app. HTML tags are not rendered in Application tab hover text. Privileges control some of the content users see: Workflow help is visible to all users who can view a primary item and have the "View Workflow Graphically" privilege. Form help and field-level help are based on users' field privileges. For example, users who do not have privileges to see fields in the Advanced section will not see help content for those fields. VIEWING CUSTOM HELP FOR ITEMS Custom help is available to users from state and transition forms for primary and auxiliary items. Custom help is available on quick forms and custom forms. Note: If you have removed the help and workflow icons from custom forms, users will not have access to Workflow or Form help. Depending on the content you provide in SBM Composer, help is available in the following areas for items: Workflow Help Contains information describing the process items follow, including a graphical view. Information about each transition, state, and decision is also shown. Depending on administrative settings, open workflow help from any item by selecting the Get help for this application link on the Actions drop-down list, or clicking the workflow icon ( ). Transition Help 4 Serena Software

5 Viewing Custom Help for Items Hover over any transition button on a state form to view provided help content. Form Help For transition forms, provides information about the transition and fields on the form. For state forms, provides information about the current state, available transitions, and fields on the form. Depending on administrative settings, open form help from any item from the Actions drop-down list or from the help icon. If Custom form information is also shown, if it was provided. Field-Level Help Hover over the name of any field that includes a dotted underline to view a shortened version of the provided help for that field. As users move through field content on the help page, the field is highlighted on the form. When they hover over fields on the form that contain help content, the help page automatically moves to those fields. Customizing the SBM User Workspace Online Help Files In most cases, the SBM User Workspace online help system will meet the needs of your users. If you have an understanding of HTML, however, you can do any of the following: Modify the text in individual help files. Add links pointing to other HTML files within individual help files. Add images to individual help files. You cannot, however, modify the structure of the help system, including any of the following: Names of individual files Table of contents Template properties, such as colors and logos Search properties To customize the content in files for the SBM User Workspace help system, perform the following steps: 1. Launch SBM System Administrator. 2. From the File menu, select Get Files From Database. This ensures that all help files and SBM User Workspace templates stored in the database are placed in your file system. 3. Navigate to the bin\help subdirectory of your SBM Application Engine directory. This subdirectory contains the HTML files used by the help system. Providing Custom Documentation for Serena Business Manager 5

6 Customizing the SBM User Workspace Online Help Files 4. Open the HTML file that you want to customize in a text or HTML editor. Tip: To determine which file to customize, open the help topic from within the SBM User Workspace, right-click in the browser window, and then select Properties (Internet Explorer) or View Page Info (Firefox). Note the file name associated with the help topic. 5. Modify text content as needed. You can also add blocks of text if you use HTML tags as they are used in the file. Note: Any new terms that you add to the files will not appear in search results, because the search index is built before the help ships. 6. To add an image to the file, first copy the image file to the bin\help\images directory. Then, in the HTML file, include an img tag in the location where you want image to appear: <img src="images/filename.png" alt="shortdescription"/> 7. After modifying help files as needed, stop the SBM Application Engine Web Server, open SBM System Administrator, and then select Put Files Into Database from the File menu. All help files on your local machine are moved to the database. 8. Start the SBM Application Engine Web Server. ABOUT SERENA Serena Software, Inc. provides Orchestrated IT solutions to the Global Serena's core purpose is to advance the business value of IT. Our 4,000 active enterprise customers, encompassing almost one million users worldwide, have made Serena the largest independent ALM vendor and the only one that orchestrates DevOps, the processes that bring together application development and operations. Headquartered in Silicon Valley, Serena serves enterprise customers from 29 offices in 14 countries. Serena is a portfolio company of HGGC. CONTACT Website: Copyright 2015 Serena Software, Inc. All rights reserved. Serena, TeamTrack, ChangeMan, PVCS, StarTool, Collage, and Comparex are registered trademarks of Serena Software, Inc. Change Governance, Command Center, Dimensions, Mover and Composer are trademarks of Serena Software, Inc. All other product or company names are used for identification purposes only, and may be trademarks of their respective owners. Revised 4 May Serena Software