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, Perl, 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 <XYZ> Reader, where <XYZ> 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,