DEVELOPER GUIDE PIPELINE PILOT INTEGRATION COLLECTION 2016 Copyright Notice

©2015 Dassault Systèmes. All rights reserved. 3DEXPERIENCE, the Compass icon and the 3DS logo, CATIA, SOLIDWORKS, ENOVIA, DELMIA, SIMULIA, GEOVIA, EXALEAD, 3D VIA, BIOVIA and NETVIBES are commercial trademarks or registered trademarks of Dassault Systèmes or its subsidiaries in the U.S. and/or other countries. All other trademarks are owned by their respective owners. Use of any Dassault Systèmes or its subsidiaries trademarks is subject to their express written approval.

Acknowledgments and References

To print photographs or files of computational results (figures and/or data) obtained using BIOVIA software, acknowledge the source in an appropriate format. For example: "Computational results obtained using software programs from Dassault Systèmes BIOVIA. The ab initio calculations were performed with the DMol3 program, and graphical displays generated with Pipeline Pilot."

BIOVIA may grant permission to republish or reprint its copyrighted materials. Requests should be submitted to BIOVIA Support, either through electronic mail to [email protected], or in writing to:

BIOVIA Support 5005 Wateridge Vista Drive, San Diego, CA 92121 USA Contents

Chapter 1: Introduction 1 Creating Subprotocol Components 32 Who Should Read this Guide 1 Data Flow 32 Requirements 1 Creating the Interface 32 Additional Information 1 Ports 33 Chapter 2: Creating Components 2 Global Properties 33 Review-o-Matic Component 2 Reusing Subprotocol Components 33 Standard Component Categories 2 Subprotocol Customization Checklist 34 Readers 3 Organizing your Saved Components 35 For Each Data Components 4 Publishing your Components 37 Writers 4 Chapter 3: Creating a Package 39 Viewers 5 Package Deployment Checklist 39 Calculators 5 Planning Data Record Types 40 Reporting 6 About the Type of a Data Record 40 Filters 6 Best Practices for Creating New Data Record Validator Filter Components 7 Types 40 Converters 7 Adding Components to Packages 41 Utilities 8 Adding Package-Specific Components 41 Utility Subfolders 8 Component Creation Checklist 41 Manipulators 9 Adding Protocol Examples 42 Learners 9 Naming and Organizing Example Protocols 42 Customizing the Component Interface 10 Protocol Examples Checklist 42 Configuring Parameters 11 Adding Regressions 44 Parameter Enabling 13 Regression Checklist 44 Parameter Customization Checklist 14 Documenting a Component Collection 44 Parameter Groups 15 Parameter Groups Checklist 16 Configuring Ports and Icons 17 Documenting Component Help 19 Summary Help 20 Guidelines for Writing Summary Help Content 20 Description Help Content 21 Guidelines for Writing Description Help Content 22 Formatting Conventions 23 Cross-Referencing with Links 24 Adding Links to Components 25 Component Creation Checklist 26 Manually Publishing a Component 27 Publishing a Component as Part of a Package 27 Data Selection Checklist 28 Functionality Checklist 29 Performance Checklist 29 Naming Convention Checklist 30 Chapter 1: Introduction

You can extend Pipeline Pilot by creating your own components and protocols. These new items may be for your own use, or they can be "published" to a shared area for others to use. You can customize Pipeline Pilot to provide domain-specific functionality or examples, or deliver ready-to-use applications. This guide begins by describing the process for creating your own components, presented in several chapters. It is often the case that more than one component is desired as the outcome of a development process. The last part of this guide covers how to develop and deliver larger projects as "component collections". Note: You can develop new components using different language-based tools, such as .NET, , and Java. Information on developing components with these kinds of tools is outside the scope of this document. For further details, see the language-based integration publications in the Help Center Developers tab (Server-side Integration > Language-based Integration).

Who Should Read this Guide This guide provides information about how to create new components or design a new component collection. It assumes you have some familiarity with using Pipeline Pilot Client and that you already have an idea about what kind of component or collection you need to develop. Requirements To develop components, you need some experience working with components and protocols. You should have a basic understanding of how to use Pipeline Pilot and the Pipeline Pilot Client to build and run protocols. Step-by-step instructions for using the client are available in the online help. Additional Information For more information about Pipeline Pilot and other BIOVIA software products, visit https://community.3dsbiovia.com.

Introduction | Page 1 Chapter 2: Creating Components

You can design new components by customizing the interface of a standard component and then saving it with a new name. You can also create a completely new component implemented as a subprotocol. After you create your component in the workspace, you can save it to your "User Name" tab. When creating a new component, much of the work involves defining the look and feel (interface). You can customize the following component interface features: Component icons Input and output ports Component help text (including tooltip help) Parameters (values, order and grouping, exposed/hidden, internals) You frequently will also want to change the behavior (implementation). The most commonly used methods for altering implementation include: Defining scripts used in parameters (e.g., PilotScript or Perl) Invoking external code (e.g., Java libraries) Other components may be connected to define an implementation, and then wrapped into a "subprotocol" to hide complexity. This chapter covers tasks involved in creating custom components. For step-by-step instructions on using the Pipeline Pilot Client to customize components, see the online help (Help Center > Users tab).

Review-o-Matic Component It is recommended that you make frequent use of the Review-o-Matic component, which can evaluate all components in a folder for common issues. 1. From Pipeline Pilot Client, open the Components tab and search for and open the Component Review-o-Matic component. 2. Set the Component Folder to the folder of components to be validated and click Run.

Standard Component Categories First, find the component you wish to customize, and drag it into an empty workspace. You'll do all the work on the component here, then save the finished version on your user tab. But before you continue creating the component interface, you need to know what a "standard" component looks like. Trying to fit your new component into this convention will make it easier to understand and use. So, take a little time and review some of the standard component categories. When end users start working with a new component, they expect to find it analogous to a previously- seen "standard" component; then, they can use their experience with the pre-existing component to help them understand and use the new component. While none of these standard components features are "required", following these standards gives your end users a head-start in understanding using your new components. The component categories include: Readers Writers

Creating Components | Page 2 Viewers Calculators Reporting Filters Converters Utilities Manipulators Learners Tip: It is typical to save your components in a hierarchy reflecting these categories, a topic discussed later in this chapter.

Readers The most common standard component is a reader; indeed, often more than one reader is available in particular domains. Each data record type should have its own reader. If multiple formats are available, you have a choice: a single reader with a Format parameter, or separate readers for each format. If the parameters are similar, a single reader is appropriate. Multiple readers are more appropriate if the parameters for each format have unique elements (where a unified reader would have so many disabled parameters that it would be difficult to understand). The standard features of a reader include: Feature Description Component name The component name should be Reader, where is the data record type or a combination of the data record type and the format. For clarity, your name should end with the word "Reader" (e.g., Delimited Text Reader). Icon Set the icon type to Document. Ports There should be no input port.

Page 3 | Pipeline Pilot • Developer Guide Feature Description Parameters A reader component should include the following parameters: Source: A reader of files should have a Source parameter (with type URLType). A reader of directories should have a Directory Path parameter, (with type DirectoryPath). Maximum: A Maximum parameter (type LongType) specifies the maximum number of outputs. It should be nested under the Source parameter. SourceTag: A SourceTag parameter (type StringType) specifies if the property SourceTag is defined on the outgoing data records. The standard set of legal values is: None, Filename, FilenameAndExtension, FullFilename, ZipFilename, Number, Letter. It should be nested under Source parameter. Keep Properties: A Keep Properties parameter (type PropertyPreviewType) specifies a list of property names to keep on the data record (all other properties are removed). This is also useful for inspecting the source to see what properties are in it.) It should be nested under the Source parameter. Recurse Directories: For directory readers, a Recurse Directories parameter (type BoolType) declares if a single level of the directory is searched, or if the search is recursive. It should be nested under the Directory Path parameter. Folder location Publish your reader components in a "Readers" folder. For Each Data Components There is a special kind of reader (For Each Data) that accepts the name of the source from a property on the input data stream, then reads from that source until complete, repeating this process as long as there is input. For Each Data components differ from standard reader components because they have an input port, and instead of a Source parameter, they include a Source Property parameter. For clarity, component names of this type should end with the word "For Each Data" (e.g., URL Reader For Each Data). Writers Writers are the mirror image of readers. It is typical (though not required) to provide a writer for each format you can read. The standard features of a writer include: Feature Description Component name The component name should be Writer, where is the data record type or a combination of the data record type and the format. For clarity, your name should end with the word "Writer" (e.g., Text Writer). Icon Set the icon type to Document.

Creating Components | Page 4 Feature Description Ports There should be no output port. Parameters A writer component should include the following parameters: Destination: A writer should have a Destination parameter (type URLType). Maximum: A Maximum parameter (type LongType) specifies the maximum number of records that are written. It should be nested under the Destination parameter. ifFileExists: An IfFileExists parameter (type BoolType) specifies the behavior if the destination is a file and already exists. The standard set of legal values are: Overwrite (the default), Append, and Halt. Folder location Publish your writer components in a "Writers" folder.

Viewers A viewer displays the incoming data using some application on your client. You can create one or more data type-specific viewers (i.e., "XYZ Viewer", where is the name of your new data type), and place it in your "Viewers" folder. Often, a given area has a set of task-specific viewers that make it simple to inspect the data in a given manner. For example, the Sequence Analysis collection has several viewers optimized for different tasks, including Clusters GO Chart Viewer, Clusters Heat Map Viewer, Clusters Parallel Coordinates Plot Viewer, Gene Subset Viewer, Heat Map Viewer, and Selection Count Viewer. If there is a set of common views that are typical in your domain, you may wish to create separate viewers for each. Best Practice: If possible, design your viewer to work so end users do not need to know in advance how to apply any complicated upstream processing to the data.

Calculators Calculators are a special type of component that allows for the generation of a specifically-named property on-the-fly (i.e., without having to explicitly drag in a particular component). Having a set of pre- defined calculators in your package allows end users to immediately understand a set of properties that they can easily generate whenever they have a particular data record type. The standard features of a calculator include: Feature Description Component name The name is typically the name of the property to calculate (e.g., AlogP). If a particular calculator bundles multiple calculations into a single component, the name should reflect the class of calculations that the component contains (e.g., Molecular Fingerprints). Prepending the data record type to the name is a good practice (i.e., "Molecular XYZ"). Icon Set the icon type to Calculator.

Page 5 | Pipeline Pilot • Developer Guide Feature Description Parameters A calculator component should have an Output parameter (type StringType). The names of the properties it can calculate are given as legal values. Do not use special characters or spaces in the names, only alphanumerics and underscores. Other parameters are allowed, but all must default to reasonable values. These are the values that are used when the property is calculated by name. Folder location Publish your calculator components in the "Calculators" folder.

Reporting Reporting components are used to create visually-appealing output of your single data record, some view of the data record, or a summary display of information about a set of data records. An example of reporting components are the renderers previously discussed; these components take individual data records and prepare them for display in the HTML Viewer and the Data Record Tree Viewer. Other example may be specific to your data record type. You can use any of the reporting components (pie charts, text, bar charts, tables, etc.) in the creation of new reporting components that make it easy for end users to display and inspect new data record types. The standard features of a reporting component include: Feature Description Component name The name suggests the type of display to perform. For example, for rendering components, names of the form "Render XYZ", where is the data record type, are common. Icon Set the icon type to one of the following Report icon types: ReportChart, ReportColumn, ReportDrawing, Report, ReportSubprotocol, ReportTable, ReportText, ReportWriter, or ReportViewer. Parameters Strive to default all parameters to reasonable values. The reporting subsystem can be complicated for new users to understand, so if things work out-of-the-box, then later adjusted if necessary, it will make the components more valuable to first-time users. Folder location Publish your reporting components in the "Reporting" folder.

Filters Filters are components that split the data stream between their Pass and Fail ports. Typically, some test is performed on each data record. Based on the test results, the record is said to "pass" (and is sent out the Pass port), or "fail" (and is sent out the Fail port). A well-behaved filter should pass each incoming data record out to either the Pass or Fail port, and generate no additional records. This means the count of records output by the Pass and Fail ports will equal the count of records input. The standard features of a filter include:

Creating Components | Page 6 Feature Description Component name The name is of the form "XYZ Filter", where is a description of the filtering operation (e.g., Top N Filter). Icon Set the icon type to Filter. Ports The Input port, the Pass port, and the Fail port, should all be available on the component. Folder location Publish your filter components in the "Filters" folder. Validator Filter Components There is a special class of filter (called a validator) that tests if the input data record is a legal instance of a given data record type. These kinds of filter components are named "Is XXX Filter", and have no parameters (e.g., Is Property Defined Filter). Converters Converters are components that convert the incoming data record type to a different data record type. For example, you may wish to convert a Materials molecule to a (standard chemistry) molecule; a component for this task would be called Materials Molecule to Molecule. A closely-related class of components is the "serializers": components that create a serialized format of the contents of the data record and put it into a property, or take a serialized representation and convert back into a data record. The standard features of a converter component include: Feature Description Component name The name describes the conversion to perform. The standard convention is "XYZ to 123", where is the input data record type, and <123> is the converted data record type (e.g., Property to Text Query). For serializers, the convention is similar. The serialization step is named to , e.g., Molecule to SMILES. The deserialization step is named from , e.g., Molecule from SMILES. Icon Set the icon type to Component. Ports The Input port data type should be set to the desired input type. The Output Pass port data type should be set to the converted data record type. The contract of the component should be that if the incoming data record type is not appropriate, the record is passed unchanged out the Fail port. However, turning on the Fail port is optional. Folder location Publish your converter and serialization components in a "Converters" folder.

Page 7 | Pipeline Pilot • Developer Guide Utilities Utilities are components that perform special-purpose functions, but are typically not used by the casual end user. One utility component type we recommend are generators that create empty copies of each of your new data record type. This can be useful for testing and debugging. These types of components are modeled after the Generate Empty Data component. The standard features of a converter component include: Feature Description Component name The name is of the form "Generate Empty XYZ", where is the data record type (e.g., Generate Cloned Data). Icon Set the icon type to Generator. Ports Only the Output Pass port should be made available. Parameters A utility component should have a NumberToGenerate parameter (type LongType). Set the default value to "1". When executed, it should generate a data record of the specified type, with minimal contents. However, all required properties and child nodes should exist (i.e., it should successfully validate as a legal example of that particular data record type). Folder location Publish your utility components in the "Utilities" folder. Utility Subfolders Publish your utility components in the Utilities folder. Additional subfolders that are common for utility components include: Folder Description Internals Components used by advanced protocol writers, or are needed by the system to work correctly. Components published in the Internals folder are not included in the Search results. Deprecated For older components that were replaced by more recent components. These older components remain available to allow older protocols to work, or to allow users to utilize at their own risk. Protocols that include deprecated components are not guaranteed to work in future releases. Components published in the Deprecated folder are not included in the Search results. Prototypes Components under development, that may or may not be fully supported in future releases. This is commonly done to allow early access to potential new functionality in the system. However, the final release of prototype components may use a different interface, and so protocols written with prototype components may not function in future releases. Debug Components used during protocol development, but are not expected to remain in the protocol after it is finished and released.

Creating Components | Page 8 Best Practice: You do not need to append the word "Utility" to subfolders in Utilities; the context should make that clear.

Manipulators Manipulators are components that change the incoming data record in some way (e.g., by adding or removing properties). The standard features of a manipulator include: Feature Description Icon Set the icon type to Component, unless your manipulator performs a specific function where another icon would be more suggestive of its action (e.g., an operation that unmerges the data should use the Generate icon). Folder location Publish your manipulator components in the "Manipulators" folder. Often, this folder will contain much of your collection's functionality.

Learners Learners are components that take as input one or more data records, and then use that information to create a new component that is added to the component database (typically, in the user's own "User Name" tab). The standard features of a learner include: Feature Description Icon Set the icon type to Learner. If the new component is a model of the incoming data, use the Model icon for the new component. Ports Typically, a learner has no output ports. However, you can use the Output Pass port to output information about the learn operation for later use (or user inspection), and use the Output Fail port to send any incoming data records that were rejected for learning, for whatever reason.

Page 9 | Pipeline Pilot • Developer Guide Feature Description Parameters If users need to specify a set of properties for the learner, add a UseProperties parameter as a StringType. The values are: AllPropertiesOnFirstData, CalculablePropertiesOnFirstData, PredefinedSet, or UserSet. Set the default value to "PredefinedSet". You also need to add the following parameters (nested under UseProperties): PredefinedSet (StringType): Contains a legal value list of properties that would be typical to use, with some nice default set already selected. UserSet (StringType): Empty IgnoreProperties (StringType): Empty Note: There is a Calculate Properties component that implements the appropriate functionality of this set, and can be used (within a subprotocol) for convenience of implementation.

Folder location It is customary to have a particular folder name on the user's tab into which the new component is placed, but this is not required.

Customizing the Component Interface With some idea of how your new component should look, it's now time to cover details about the process of creating a component. The Edit dialog is where you change the interface. It includes tabs for help text, ports and icons, parameters, and implementation. (You also use this same dialog to customize a Subprotocol interface.) To open the Edit dialog: Right-click the component and select Edit. The Edit dialog opens. From here, you can do all your customizations. For example, here’s the Edit dialog for the Delimited Text Reader:

Creating Components | Page 10 Edit dialog for Delimited Text Reader component

Configuring Parameters Parameters are used to determine the properties and behavior of a component. Use the Parameters tab in the Edit dialog to configure your custom parameters. You can modify existing parameters and add/define new ones. Parameters are generally organized by group (explained later in this chapter).

Page 11 | Pipeline Pilot • Developer Guide Parameters for Top N Filter component For tips on using the Parameters tab, point over a toolbar button:

Toolbar button help for Parameters tab When the Parameters tab is displayed, you can open another dialog (Define Parameter) for customizing your parameters. To add a new parameter: To modify an existing parameter: Click Add Parameter . Select the parameter name and then click Edit Parameter .

Creating Components | Page 12 Define Parameter dialog The parameter attributes you can configure include: Parameter Attribute Details Parameter help The text you type will provide your end users with a description of what the parameter is intended to do. HTML markup is supported in this field, so you can apply formatting and separate information into multiple paragraphs and bulleted lists. Parameter name Provides a way to assign a unique name for the parameter that will help end users understand your interface. Parameter type All parameters need to be configured as a certain type. Parameter types have an associated range of possible values and uses. Numerous types are available and you can also define your own custom types. Required to run protocol If the parameter requires a value at run time, you need to select this checkbox. Required parameters are displayed in red, so end users know they must to provide a value to run the protocol. Array For parameter types that accept multiple values (an array), select Array. Then, type each value on a separate line in the Legal Values tab

Parameter Enabling You can configure your parameters so they only apply under certain conditions. This is known as "parameter enabling". If the condition applies, the parameter is enabled and its value is used by the component or protocol. When the condition does not apply, the parameter is ignored. To provide this

Page 13 | Pipeline Pilot • Developer Guide functionality, develop your own scripts. Use the Legal Values, Validation Script, Enable Script, and Legal Values Script tabs in the Define Parameters dialog for this purpose. Parameter Customization Checklist The following information offers suggestions for customizing components that are compatible with existing components and protocols from an operational and cosmetic standpoint. Although situations may arise where deviating from these guidelines is appropriate (and even necessary), end users can quickly work with your components if they have a familiar look and feel, and follow the recommended styles as closely as possible. Do this: Details: Done? Limit parameters The fewer parameters, the better. Each one causes additional cognitive overhead in the end user’s mind. Omit obscure, hard-to- understand, or unlikely-to-be-changed parameters. Use proper naming conventions Parameter names should use initial caps with spaces separating words. No underscores. Examples: Initial Expression, Keep Calculated Properties. One exception to this guideline is that the spaces should be omitted when using "standard" parameters, such as SourceTag, UseProperties, PredefinedSet, etc. Assign appropriate types to your For Boolean parameters, use the Boolean parameters parameter type, not a String parameter with Yes/No, On/Off, True/False, etc. as legal values. Assign list boxes to multiple choice For multiple related Boolean parameters, parameters consider using a multiple select list box (e.g., see the Output parameter for the Molecular Properties component). Enable/disable parameters with scripts If certain parameters apply in some situations but not in others, use the Enable Script tab in the Define Parameter dialog to enable and disable these parameters, according to the values of other parameters. This gives the end user visual clues about which parameters are applicable in a given context. Be thorough Your text should fully explain how to use the parameter. Include all relevant information that will help your end users understand how to set values for the parameter.

Creating Components | Page 14 Do this: Details: Done? Be precise Ensure your content is not too vague. Do not assume your end users will understand that you are implying anything. Be explicit instead. Remember that the end user does not know your context the way you do. Be consistent If you have a group of components that use the same parameter, be sure to reuse the help text in all the components. If you have a group of components that uses similar parameters, use consistent grammatical construction and phrases for each parameter. Define options For parameters that have multiple values that are available to select from a drop-down list, define the behavior of each option to help end users understand their options. For three or more options, use bulleted list items. Avoid wordiness Parameter help should be as brief as possible without omitting necessary information that helps end users make decisions. Avoid listing options and then saying "former" and "latter" in the next sentence to refer to such options. Instead, provide the details for each option directly after the option. Chunk your content, so it’s clear and to-the-point. Provide examples When appropriate, provide a brief example to enhance usability. For example, for a "range" parameter, add "1-2-3". Test your facts Double-check facts and test your component to ensure that the information you provide is 100 percent accurate.

Parameter Groups A group is a way to organize parameters into categories based on their purpose. Related and similar parameters are located in the same group so they are easy to find. This is especially useful for complex components that include a large number of parameters. It makes the component easier to maintain. Groups are expandable and collapsible by pressing [+] and [-], so you can hide or show parameters for a given group directly in the dialog.

Page 15 | Pipeline Pilot • Developer Guide Parameter groups for "Expression" and "Additional Options" Parameter Groups Checklist

Do this: Details: Done? Stay on top of your groups from the get-go After you add new parameters, be sure to group them in the Parameters tab. Consider GroupType parameters When you add a new parameter, it is added as a string type, which by default, allows you to specify a string value for the parameter. You can change this to any type that is appropriate for the parameter. When a set of parameters naturally work together, it may be beneficial to group them by creating a GroupType parameter and placing the parameters inside. A GroupType parameter does not accept a value. Group parameters only if it simplifies the If a component has less than five interface parameters, grouping usually isn’t necessary. Group parameters according to function You can add your own groups and you can add members (parameters) to a group. Put some thought into your parameter and All parameter members within a group group names require their own unique names, even if they are similar. Group consistently across components For example, if Maximum is grouped under Source in Component A, repeat this for all other components that use the same set of parameters.

Creating Components | Page 16 Do this: Details: Done? Organize parameters for usability Place the most important parameters, which are more commonly used, at the top of the list. Place required parameters, which need a value at run time, at the top level and visible by default. Place advanced parameters, which are less commonly used, inside the group. Reuse your work Whenever possible, select an existing parameter to become the group parameter instead of creating a new group parameter. Keep it simple Keep parameter hierarchy shallow; go two levels into the hierarchy if necessary.

Configuring Ports and Icons Use the Ports and Icons tab in the Edit dialog to configure ports and icons. These settings are included in your component documentation, and are displayed in the Help window, after your description help text.

Page 17 | Pipeline Pilot • Developer Guide Ports for Top N Filter Follow these guidelines for configuring your icons and data ports: Guideline Details Use an appropriate icon, since it provides a visual clue for Assign an icon that visually conveys your end users what your component is designed to do. Many options are available. Follow the guidelines provided in section Standard Component Categories. Fully configure all your ports For each type of port used with your component, specify if the supported data is generic and/or molecular. Check or uncheck the options accordingly. Remove ports not used by your component by clearing both checkboxes. Do not assume end users will understand the data flow on For the Fail port, be sure to explain their own under what conditions an object can fail.

Creating Components | Page 18 Guideline Details Add comments where necessary Comments are useful to explain requirements for the data, such as the presence of certain properties. Be specific about data records and their properties by describing why data records are sent to a Pass versus a Fail port (explain the precise criteria used to define this behavior).

Documenting Component Help When creating a new component or modifying an existing one, make sure that the component and all of its parameters are fully documented. The Pipeline Pilot Client makes this process relatively simple by providing text editors for your content and formats, and by storing this information in the component XML file for easy access.

Component help for Custom Filter (PilotScript)

Page 19 | Pipeline Pilot • Developer Guide Summary Help The summary help is a brief statement that explains what you can do with the component. The text you enter in this field is displayed in bold when end users view your information in the Help window. It is also used as fly-over help in the Explorer window (as a yellow shaded box).

Purpose statement for a component Guidelines for Writing Summary Help Content

Guideline Details Make it brief Summary text should be brief statement, since it is also used as fly-over help in the Explorer window. Brief means no more than one sentence in length (without a period), 10- 20 words maximum. Note that the flyover help may truncate after it reaches a maximum number of characters. If your statement is too wordy, there may not be enough room to display your text in the yellow popup box.

Creating Components | Page 20 Guideline Details Begin with an action word The statement should start with a verb. Correct: "Reads data records from a …" Incorrect: "Data records are read from a …" No period after brief statement for consistency No need to type period at the end of the statement (it is not a sentence). No blank lines before or after Be careful that your purpose statement does not include any blank lines after the text. Do not press ENTER in the Edit dialog to add any blank lines. Any extra lines included in the purpose text field are included in the fly-over help, making the yellow popup box display an extra blank line below the text. This increases the size of the rectangular box. If you are inconsistent about this, some of your fly-over help will have a larger yellow box, while other help will display a single line of text in the Explorer window. These little inconsistencies make a big difference in the overall quality of your user interface. Avoid wordiness and unnecessary words Do not use "This component" or "The component" in the purpose statement. Correct: "Reads data records from a …" Incorrect: "This component reads data records from a …" Do not substitute the component or protocol name Take the time to write something meaningful for the purpose text if possible: so users get an idea why they would want to work with your component: Correct: "Reads data records from a Microsoft Excel file (.xls) stored on the client" Incorrect: "Excel Reader (on Client)" Description Help Text"

Description Help Content The description help text contains detailed information about the component or protocol. It is displayed below the purpose statement in the Help window. It supports HTML markup for bold, italics, bulleted lists, and tables. It also supports hypertext links to other components and protocols, and to external URLs. All of your detailed information for end user assistance belongs in this area of the component reference help.

Page 21 | Pipeline Pilot • Developer Guide Guidelines for Writing Description Help Content

Tip Details Provide adequate details The description help should add detailed information that fully explains how to use the component or protocol. Include all information that helps your end users understand how to work with the component or protocol. Provide relevant details, so end users know what to expect. Important parameters should be described in the Description. Describe what they do, but don't go into detail about how they work (be sure to provide this level of detail in the parameter help instead). Avoid redundancy Do not repeat the same information in the description help that is used in the purpose statement, especially in the first paragraph. Redundancy takes up UI space, is time- consuming to maintain, and looks tacky. What's more, users often get frustrated when they see repetitive information that does not answer their questions ("How do I" and "What is this"). Prioritize information If a component can be used in multiple ways, describe the most common usage in the initial part of the Description. To explain less- common usages or behaviors of the component, add a Notes section. Include cross-references To cross reference related components, user guides, and external URLs, add a See Also list and include links to these other resources (see below for details). Cross-reference dependencies If a component is dependent on another upstream component to produce output or generate something, then the dependent component should always mention the other component it requires. Provide a link to this other component in a See Also section (see below for details). Use a minimalist editing style Be concise. Omit needless words. Avoid phrases such as "this component" to reduce wordiness. No need to say, "This component does this…". Instead, just say, "Does this…".

Creating Components | Page 22 Tip Details Avoid elegant variation Do not describe the same thing in two or three different ways, just to include extra text in your description. If you do not require a lengthy explanation, there is no need to fill up space with words. Talk to your reader if necessary as "you" Use First person singular ("you" instead of "the user"). Do not leave the description blank No component is too simple for a basic description. Formatting Conventions The Help Text tab supports HTML markup. Use the right-click menu to select HTML formatting. Use the following typographical and HTML/CSS conventions when formatting your text:

Item Format Example Boolean Unquoted, except for multi-word legal values True, False, PredefinedSet, StdDev. values and separated by spaces or values in all lowercase "Remove Uninformative Bins", pre-defined (should be quoted). "brlr", "FitSummary and FitPlot". list values Bulleted list Wrap the entire list with