GETTING STARTED WITH INSIGHT PLUGINS GUIDE BIOVIA INSIGHT 2018

Transcription

1 GETTING STARTED WITH INSIGHT PLUGINS GUIDE BIOVIA INSIGHT 2018

2 Copyright Notice 2017 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 DMol 3 program, and graphical displays generated with BIOVIA Insight." BIOVIA may grant permission to republish or reprint its copyrighted materials. Requests should be submitted to BIOVIA Support, either through electronic mail to biovia.support@3ds.com, or in writing to: BIOVIA Support 5005 Wateridge Vista Drive, San Diego, CA USA

3 Contents Chapter 1: Introduction 1 Permissions 2 Additional Information 3 Chapter 2: Detailed Descriptions of Plugins 4 Accessing Deep Properties 4 Plugin help in the Insight web client 5 Good practice in preparing plugin help 6 File Adapters 7 File Adapter plugin help 7 File Adapter plugin protocol rules 8 Data Generators 8 Data Generator plugin protocol rules 8 Accessory protocols 9 Data Generator plugin help 10 Data Generator plugin protocol rules 11 Widgets 11 Widget template 11 Plugin developer mode 11 Widget plugin help 12 Widget plugin protocol rules 13 Widgets advanced options 14 Data Connector 14 Single Record View Mode 14 Conditional formatting 14 Title Template 15 Accessing Deep Properties 15 Accessing Deep Properties 15 Calculators 15 Calculator template 16 Calculator plugin help 16 Calculator plugin protocol rules 18 Accessing Deep Properties 19 Exporters 19 BIOVIA Insight Getting Started with Insight Plugins Guide Page i

4 Exporter template 20 Exporter plugin help 20 Exporter plugin protocol rules 22 Accessing Deep Properties 23 Chapter 3: Plugin Metadata 24 Insight Metadata parameter group 24 Plugin options and parameter metadata 25 Plugin categorization and supported record types 29 Chapter 4: Developer Tools 30 Requirements of plugin protocols 30 Plugin template protocols 30 Useful components 31 Insight Cache Reader 31 Insight Cache Writer 31 Widget Viewer 31 Convert Range to Maximum 31 File Adapter Range Filter 31 Promote and Rename Deep Properties 31 Create Globals Containing Names 31 Moving, renaming, and deprecating plugin protocols 32 Useful Insight web client tools 33 Document Summary tab 33 Record Inspector Widget 34 Error Handling 34 Chapter 5: Example Custom Plugins 35 Building a new file adapter plugin 35 Advanced configuration 36 Building a new data generator plugin 37 Advanced configuration 38 Building a new widget plugin 39 Advanced configuration 41 Accessing deep properties 42 Building a new calculator plugin 43 Building a new exporter plugin 45 Page ii BIOVIA Insight Getting Started with Insight Plugins Guide

5 Chapter 1: Introduction In Insight, the base functionality of the application can be extended by writing "plugins". Plugins are small pieces of functionality in the Insight web client that can provide solutions to your users' problems and workflows that are not handled by the default functionality. Data acquisition, manipulation, visualization, and export are all extensible with the use of plugins. In fact, the majority of the default functionality in Insight is built using plugins. Users in the Insight/PluginAuthors group can develop custom plugins by creating Pipeline Pilot protocols. Plugin protocols can use the full range of generic, scientific, reporting, and other components available in Pipeline Pilot to provide their functionality. The types of plugins that are available are: Plugin Type Description Insight Availability File Adapters Data Generators Widgets Protocols that load data from files. These can also customize the behavior of an alreadysupported file type. Protocols that load arbitrary data into Insight. The most powerful data import extension, making any data that can be put on a Pipeline Pilot data record available to the application. Protocols that use reporting components to generate visualizations of document data. In the Insight web client, Widgets are placed into drag-and-drop panels on a tab. Widget plugins are saved and stored in users' documents and templates. Each application of any widget can be configured and customized individually. Load data from file Home Page: Import Data From File Document toolbar: Import Data File... Load data from another source Home Page: Import Data From Data Generator Document toolbar: Import Data Data Generator... Provide data visualization: Document toolbar: Add Widgets The Add Widget dialog only displays widgets appropriate to the current data record types. Introduction Page 1

6 Plugin Type Description Insight Availability Calculators Exporters Protocols that generate or manipulate properties in the document data. Protocols that handle the output of data from Insight. These can create files, reports, or save data into other repositories such as databases. By default, Exporter protocols are aware of document selection and filter state. Provide data manipulation Document toolbar: Calculate The Run Calculator dialog only displays calculators appropriate to the current data record types. Export data for sharing Document toolbar: Export The Export dialog only displays exporters appropriate to the current data record types. Template and example plugins are available in Insight to guide you and to make creation of new plugins easy. Plugins are all always stored in the "Protocols/Web Applications/Insight" folder in the Pipeline Pilot Professional Client in a subfolder appropriate to the type of plugin protocol and the web client functionality. Tip: Always begin development of a custom plugin by loading a template. Press CTRL + SHIFT + N or choose File New Protocol from Template... in the Pipeline Pilot Professional Client to view available templates. Permissions Plugin developers must be in the Insight/PluginAuthors group to access plugin templates and to view, edit, and save into the plugin directories. 1. Navigate to the Pipeline Pilot Admin Portal: where <server> and <port> are the name of the machine where your Pipeline Pilot server is installed and the assigned Apache port 2. Login as an Administrator user. 3. Open the Security Groups page to configure your access. 4. Add the user name of the current user (or the user who wants to develop plugins) to the Insight/PluginAuthors group. 5. Click the Save button. The permissions for this group also allow users to see extra information (when available) on the Summary tab for a Document in the Insight web client: Cache Id Data Types Node Type Page 2 BIOVIA Insight Getting Started with Insight Plugins Guide

7 Additional Information For more information about Insight and other BIOVIA software products, visit BIOVIA Support on the Web: Introduction Page 3

8 Chapter 2: Detailed Descriptions of Plugins Data Generators Widgets Calculators Exporters The data types suitable for a plugin in the Insight web client are determined by the value of the Supported Data Types parameter on the plugin protocol. The standard options are "Molecule" and "Generic", but if you are preparing plugins to work with custom data you can edit this parameter to extend the list of Legal Values. Note: Refer to the Plugin Metadata section for more information on the Supported Data Types parameter. Tip: For each plugin category you should save your custom plugins in a subfolder (a new subfolder if necessary). These subfolders are displayed in the Insight web client plugin selection dialogs and assist users in categorizing and sorting. Accessing Deep Properties The Exporter, Calculator, and Widget plugins can access "deep" properties (those not at the top level of the Properties list) if the plugin protocol is configured to handle these properties. Two components should be employed to manage the access, promotion, and communication of deep properties, their names, and their values throughout a plugin protocol: Promote and Rename Deep Properties promotes deep properties to top level arrays Create Globals Containing Names creates global properties with shortened names of deep properties In order to access and handle deep properties the following should be implemented in your plugin protocol: In the protocol-level Insight Metadata parameter group, set the Retrieve Deep Properties or Keep Properties parameter to "*" so that the protocol can access any deep properties. After the Insight Cache Reader in a second pipeline the next component should be Promote and Rename Deep Properties with these parameter settings Paths to Properties to Promote should reference the protocol-level parameters (exposed as options on the plugin dialog) which should be able to accept deep properties. New Top-Level Property Names should refer to the global property names generated by the New Global Properties Containing Names parameter on the initial Create Globals Containing Names component. Subsequent components which process deep properties should use the global property names generated by the New Top-Level Property Names parameter rather than the protocol-level parameters' names (unless a Create Globals Containing Names is also used in which case the global properties must be employed instead). Detailed Descriptions of Plugins Page 4

9 For plugins which use property names in later components (for example, widgets), the first component in an initial pipeline should be Create Globals Containing Names with these parameter settings: Paths to Properties Providing Names should reference the protocol-level parameters (exposed as options on the plugin dialog) which should be able to accept deep properties. New Global Properties Containing Names should contain the same number of values as Paths to Properties Providing Names with the new global names supplied in the same order as the deep properties being loaded. Subsequent components which process deep properties should use the global property names generated by the New Global Properties Containing Names parameter rather than the protocollevel parameters' names. When plugin protocols are configured to access deep properties in this way web client users can dragand-drop items from the Properties list into the appropriate plugin parameters on a plugin options dialog. Tips: The instructions in Building a new widget plugin include configuration of deep properties handling. The IC50 Plot Example widget protocol is available to users in the Insight/AuthorPlugins group (in the Insight/Widgets/Development directory) and employs the Create Globals Containing Names and Promote and Rename Deep Properties components with a Scatter Plot. The Deep Property Average Calculator protocol is available to users in the Insight/AuthorPlugins group (in the Insight/Calculators/Development directory) and employs the Promote and Rename Deep Properties component with a Basic Statistics for Each Data calculator. Plugin help in the Insight web client Plugins provide the opportunity for Insight web clients to enter values, settings, or specify parameter options. To ensure that the Insight web client help for plugins is useful and informative for you should ensure that all plugin protocols have protocol help and all protocol-level parameters have help which describes how to use the parameter from the perspective of the Insight web client. Page 5 BIOVIA Insight Getting Started with Insight Plugins Guide

10 Good practice in preparing plugin help Tip Provide adequate details Use a minimalist style Talk to your reader if necessary as "you" Do not leave the description blank Do not use Pipeline Pilot terminology For lists of parameter values and their descriptions use bullets Format references to other parameters Make references to parameter values clear Do not include hyperlinks for protocol help Do not mention PilotScript Details Include all information that helps Insight web client users understand how to work with this custom plugin. Be concise. Omit needless words. Avoid phrases such as this exporter to reduce wordiness. For example: No need to say "This calculator performs ". Instead, just say, "Performs ". Use first person singular ("you" instead of "the user") No plugin protocol or parameter is too simple for a basic description. Insight web client users will not know anything about protocols and components. Refer to the plugin instead. The plugin configuration fields should be referred to as parameters. Do not refer to components or include Pipeline Pilot links to related components. For example, in the Edit Parameter dialog use HTML like this: <ul> <li>item One - does something</li> <li>item Two - does something else</li> </ul> If the value of one parameter can change or depend on a different setting, refer to the related parameter using italics. For example: Chemistry Column Size The size of the Chemistry Image column, in percentage points. Use quotes around values, for example: Orientation Specifies how the document is positioned on the page. "Portrait" positions the print vertically; "Landscape" positions it horizontally. Links will appear as underlined text but web client users cannot click on the contents of tooltips. Insight web client users won't know what this is or have the opportunity to use it. Detailed Descriptions of Plugins Page 6

11 File Adapters File Adapters are available in the Insight web client through the Import Data from File function (either on the home page or in an open document). File Adapters plugins are protocols that include a file reader component and are used to read data from a given file type into Insight. The name of the File Adapter protocol is used to determine which file types it can read. For example, the File Adapter that reads delimited text files is called the CSV TSV TXT Reader and so it is used when the Insight user selects a file to upload that has a file extension of either.csv,.tsv, or.txt. Like other plugins, protocol-level parameters on File Adapters are exposed in the Insight web client. File Adapter plugin help Any protocol-level parameters are available in the Import Preview, their help is similarly available in the Insight web client when the cursor is placed over a parameter. Pipeline Pilot Insight Insight Help Description The content is the parameter help The type and value and other parameter details are not available in the Insight web client. Protocol-level parameters in groups are displayed in group boxes in the Settings panel. Page 7 BIOVIA Insight Getting Started with Insight Plugins Guide

12 File Adapter plugin protocol rules Protocol termination Protocol name The protocol must terminate with at least one open pass port. The name of the File Adapter protocol is used to determine which file types it can read. The format for protocol names is as follows: <filename_extension1 filename_extensionn> Reader So, for example a protocol by the name of MOL SD SDF Reader would be registered as the reader for files ending with.sd,.mol, and.sdf. Compressed files are automatically expanded before the file name extension is evaluated. Protocol location Protocol parameters Ranges Protocol must be saved in: Protocols/Web Applications/Insight/File Adapters/Custom If the file type mappings clash with the default Insight File Adapters those in /Custom will take precedence. All File Adapter plugin protocols must have a Source parameter of "URLType" at the top level. Insight will automatically pass the path to the selected file to this parameter. To allow users to specify a range of records to import you should include a Convert Range to Maximum at the beginning of the File Adapter protocol and promote the Range to the protocol level. Then add a File Adapter Range Filter after the reader component, promoting and merging its Range parameter with the one already on the protocol. Then set the Maximum parameter on the reader component to $(Maximum) so that it uses the maximum value identified by the Convert Range to Maximum. Data Generators Data Generators are a more abstract form of File Adapter plugins. A data generator is any protocol that retrieves or creates data for Insight. This makes Data Generators ideal for pulling data from web services, instruments, and other creative sources, including online sources. Data Generator plugin protocol rules Protocol termination Protocol location The protocol must terminate with at least one open pass port. Protocol must be saved in: Protocols/Web Applications/Insight/Data Generators/<Category Name> Protocol parameters Restrictions There are no requirements regarding plugin protocol parameters. It is a good idea to provide sensible defaults for any parameters that you expose because Insight will attempt to run the protocol with defaults when the user selects it from the Load from Data Generator dialog. The default preview that the user will get will be based on the default settings. To prevent default preview you can expose at least one parameter without a value. Data Generators should not include any Reporting Collection components. Detailed Descriptions of Plugins Page 8

13 Accessory protocols A data generator protocol can also call another protocol to provide the dynamically generated data, for example as a dropdown list of values. 1. In the data generator protocol: a. Right-click the parameter that will should have a dynamically generated legal value list (a dropdown list in the Insight web client) and choose Edit Parameter... b. Click the Legal Values Script tab. c. Enter a script that uses the function RunProtocol to call the accessory protocol that will provide the dynamically generated data. 2. In the accessory protocol that is called, be certain that it: Reads in a data file. Creates a property to merge records together (such as mergeme) which will result in an array of values (using Merge Properties) and then keeps only the property that you want (using Keep Properties). Creates a global property (such as AssayNames, using a Custom Manipulator (PilotScript)) to hold the array of values to be returned to the list. 3. In the accessory protocol, click the white space around the protocol to show the protocol-level Parameters. 4. In the Parameters window of the accessory protocol, choose the Web Service tab: 5. In the Results area, click Edit Add your global property (such as AssayNames) and be certain to set the Type to String Array. Click OK. 7. Save the accessory protocol in a location outside the Web Applications\Insight directory - such as in a folder called Insight Utility Protocols on your User tab. Note: Test the protocols in the Pipeline Pilot client first. If you make changes to the accessory protocol at this point, you might need to close and reopen it first before re-testing. Page 9 BIOVIA Insight Getting Started with Insight Plugins Guide

14 Data Generator plugin help The protocol summary is displayed in the Load from Data Generator dialog as follows: Pipeline Pilot Insight Any protocol-level parameters (apart from those in the Insight Metadata group) are available in the Import Preview, their help is similarly available in the Insight web client when the cursor is placed over a parameter. Pipeline Pilot Insight Insight Help Description The content is the parameter help The type and value and other parameter details are not available in the Insight web client. Detailed Descriptions of Plugins Page 10

15 Protocol-level parameters in groups are displayed in group boxes in the Settings panel. Data Generator plugin protocol rules Protocol termination Protocol location Protocol parameters Restrictions The protocol must terminate with at least one open pass port. Protocol must be saved in: Protocols/Web Applications/Insight/Data Generators/<Category Name> There are no requirements regarding plugin protocol parameters. It is a good idea to provide sensible defaults for any parameters that you expose because Insight will attempt to run the protocol with defaults when the user selects it from the Load from Data Generator dialog. The default preview that the user will get will be based on the default settings. To prevent default preview you can expose at least one parameter without a value. Data Generators should not include any Reporting Collection components. Widgets Widget plugin protocols are wrappers for reports generated with the use of Pipeline Pilot Reporting Collection. Because custom Widget plugins use the same framework as standard Insight widgets they have access to the same layout, event handling, configuration dialog, and state saving functionality. Unlike other plugin types, Widgets continue to interact with the server beyond the initial render in response to application events. Widget template Insight Cache Reader - allows you to run the custom widget in the Pipeline Pilot Professional Client for debugging purposes. The Input port must be enabled. Placeholder 1 - replace this with appropriate data processing components to prepare the data for writing. Placeholder 2 - replace this with an appropriate writer component. The Destination parameter should be set to $(JobDir)/$(File Name) so that the exported file is stored appropriately. Widget Viewer - allows display of the output in the Insight web client. Plugin developer mode The Additional Options group of Insight Metadata parameters for widgets contains a Developer Mode parameter. When this is set to "True", Insight runs the widget in developer mode - a refresh button is added to the widget toolbar that its contents can be refreshed on-demand, dynamically updating its contents as the Page 11 BIOVIA Insight Getting Started with Insight Plugins Guide

16 underlying plugin protocol is developed. In this mode the widget options dialog will be refreshed every time the dialog is opened instead of being cached. These features alleviate the need to delete and re-add the widget to the document in order to see protocol changes. Widget plugin help The protocol summary is displayed in the Add Widget dialog as follows: The protocol summary and help text are displayed in the widget options dialog as follows: Pipeline Pilot Insight Insight Help Description The title is the name of the protocol itself The one-line description is the protocol summary The main content is the protocol help This is followed by a standard statement: "Select a parameter to see help for it." Any protocol-level parameters (apart from those in the Insight Metadata group) are available on the next page of the widget options dialog, their help is similarly available in the Insight web client when a parameter is clicked on. Detailed Descriptions of Plugins Page 12

17 Pipeline Pilot Insight Insight Help Description The title is the name of the parameter itself The main content is the parameter help The type and value and other parameter details are not available in the Insight web client. Protocol-level parameters in groups are accessed by the Advanced button on the widget options dialog, their parameter help is presented in the same way as the top-level protocol parameters. Widget plugin protocol rules Create Protocol from Template Protocol location When creating a new widget plugin, start with the Insight Widget template protocol. This template comes with all the required components and appropriate parameter defaults. This template comes with all required components and sensible parameter defaults. Protocol must be saved in: Protocols/Web Applications/Insight/Widgets/<Category Name> Declare supported data types Accurately declaring support data types is important because it prevents the Widget plugin from being enabled for inappropriate document data (chemistry Widgets for records without chemistry data). For more information, see Plugin Categorization and Supported Record Types in this guide. Page 13 BIOVIA Insight Getting Started with Insight Plugins Guide

18 Must Contain Component before Widget Viewer Let Insight manage the layout of charts When run by the framework, records are passed through the main pipeline, which must originate with an Insight Cache Reader component that contains an open Input port. This main pipeline must terminate in a Widget Viewer component. You can have some initialization components and some cleanup components but make sure that only one pipeline has an Input port and it starts with the Insight Cache Reader. Data records should flow into at least one Reporting component before arriving at the Widget Viewer component. If the component immediately upstream of Widget Viewer is an interactive chart (Scatter Plot, Bar Chart, Histogram, Line Chart, Radar Chart) then it will be embedded into the document layout as an image that is automatically resized with the layout. All other reporting components will be embedded into the document inside an IFRAME element. When possible, avoid the use of Tile Horizontal and Tile Vertical, especially with charts. When you pass multiple charts into one of the tile components you will lose the automatic chart resizing. Instead you ll get fixed-size charts in a dynamically resized container. Widgets advanced options Data Connector Widget plugins use Reporting Collection s Data Connector component to communicate record selection with Insight and other widgets in the document. This feature is automatically configured by Insight with sensible defaults that should be appropriate for most widgets. The Data Connector functionality is activated by the True/False setting of the Enable Data Connectivity parameter on the Insight Cache Reader component. Single Record View Mode By default, Widget plugins are record aggregators, meaning that they collect all records passed to them and generate a combined report or chart. Scatter Plot, Histogram, and Table are all examples of widgets that aggregate records into a single report. Insight can also run widgets in a Single Record View (SRV) mode where a report is generated for each record. Insight then adds a paging toolbar that allows the user to page through the records. The Detail View and the Molecule Viewer widgets are examples of widgets running in SRV mode. SRV mode is controlled by the Single Record Access parameter in the Insight Metadata group. When Single Record Access is "True", the two parameters in this group are enabled. The defaults for these should work for most Widgets. Internally, when Insight runs a widget protocol in SRV mode it will do so in RunToCompletion mode for each data record. All components in the widget protocol are executed for each data record passed into the protocol. Any initialization and/or finalization pipelines are also executed for each record. Conditional formatting To enable a feature of you widget to benefit from conditional formatting you should add a Color by Formatting Rule component to your widget protocol, before any reporting components. Promote the Format parameter so that it will be available on the Widget Options dialog (changing the name of the promoted parameter appropriately). Set the Color parameter on the component to the property name Detailed Descriptions of Plugins Page 14

19 that should contain the color specified by the rule. On the reporting component which should use this rule, set the appropriate parameter value to the same property name. For example, the Scatter Plot widget protocol uses the Color property on both the Color parameter of Color by Formatting Rule and the Symbol Color parameters on both Scatter Plot reporting components. Title Template Widget plugin protocols can provide a template that is used to construct the title of the widget panel in the Insight web client. This is controlled by the Title Template parameter in the Insight Metadata parameter group on the protocol. This supports patterns that are substituted for protocol name, document name, or the value of a particular parameter. For example a Scatter Plot might use a title template such as: ${Param:Y Property} vs. ${Param:X Property} This takes the value of the Y Property and the value of the X Property parameters and creates a title such as ALogP vs. Molecular Weight. Accessing Deep Properties In order for parameters on the Plugin Options dialog to accept and properly process "deep" properties (those not at the top level of the Properties list) the plugin protocol must be configured to handle these properties by setting the Retrieve Deep Properties or Keep Properties protocol parameter to *. For more information on employing deep properties refer to Accessing deep properties. Accessing Deep Properties In order for parameters on the Plugin Options dialog to accept and properly process "deep" properties (those not at the top level of the Properties list) the plugin protocol must be configured to handle these properties by setting the Retrieve Deep Properties or Keep Properties protocol parameter to *. For more information on employing deep properties refer to Accessing deep properties. Calculators Calculator plugins are able to add and manipulate properties on records in document data. These data changes are persisted when the document is saved. Calculators can take all records in a document as input, or only a selected subset of records. All Calculator protocols have an Insight Cache Writer component. During development of a custom widget this component provides a preview of data as it would be written to the data cache. When run through the web client, this component will save the records in the document. Page 15 BIOVIA Insight Getting Started with Insight Plugins Guide

20 Calculator template Insight Cache Reader - allows you to run the custom calculator in the Pipeline Pilot Professional Client for debugging purposes. The Input port must be enabled. Placeholder - replace this with calculation components. Promote any configuration parameters from this component or subprotocol to the top level to generate a configuration form in an options dialog for the calculator in the Insight web client. Insight Cache Writer - updates the data and metadata caches with the calculated properties and updates the data descriptor object that is returned to the Insight web client. Calculator plugin help The protocol summary is displayed in the Calculate dialog as follows: The protocol summary and help text are displayed in the calculator options dialog as follows: Detailed Descriptions of Plugins Page 16

21 Pipeline Pilot Insight Insight Help Descriptio n The title is the name of the protocol itself The one-line description is the protocol summary The main content is the protocol help This is followed by a standard statement: "Select a parameter to see help for it." Any protocol-level parameters (apart from those in the Insight Metadata group) are available on the next page of the calculator options dialog, their help is similarly available in the Insight web client when a parameter is clicked on. Page 17 BIOVIA Insight Getting Started with Insight Plugins Guide

22 Pipeline Pilot Insight Insight Help Description The title is the name of the parameter itself The main content is the parameter help The type and value and other parameter details are not available in the Insight web client. Protocol-level parameters in groups are accessed by the Advanced button on the calculate options dialog, their parameter help is presented in the same way as the top-level protocol parameters. Calculator plugin protocol rules Create protocol from template Don t manipulate chemistry When creating a new calculator plugin start with the Insight Calculator template protocol. This template comes with all required components and sensible parameter defaults. Calculator plugins should not create or manipulate chemistry on the records that pass through them. This functionality isn t currently supported and may corrupt document data. Don t create or manipulate deep properties Report progress Protocol location Calculated properties must be on the top-level of the record. Some calculators have to do a lot of up front work before they can begin processing any records (for example, those that generate mathematical models). For these calculators it can appear to the end user that the calculator is not progressing. To provide information on calculators' progress during initialization you can send messages to the user's browser using the SendMessageToClient() PilotScript function. Protocol must be saved in: Protocols/Web Applications/Insight/Calculators/<Category Name> Detailed Descriptions of Plugins Page 18

23 Declare supported data types Declare output properties on the protocol Do not declare a parameter called Output on your protocol Must contain Restrictions Accurately declaring supported data types is important because it prevents the Calculator plugin from being enabled for inappropriate document data (for example, chemistry Calculators for records without chemistry data). For more information, see the Plugin Categorization and Supported Record Types section in this guide. The Insight Metadata > Output Properties parameter is used by the framework to identify which properties are being added or modified by the calculator. All other properties are stripped off before the records are persisted so you must either set the protocol-level parameter or set it dynamically in the protocol. Example of static use: ALogP Examples of dynamic use: Simple Math Molecular Properties When a protocol declares a top level parameter called Output, it becomes a calculable property available in Pilot Script. Insight calculators do not support being used as calculable properties. More importantly, you might accidentally overwrite the functionality of an existing calculable property on the system. When run from the web client, records are passed through the main pipeline. This must begin with an Insight Cache Reader component with an open Input port. This main pipeline must terminate in a Insight Cache Writer component. Calculators should not include any Reporting Collection components. Accessing Deep Properties In order for parameters on the Plugin Options dialog to accept and properly process "deep" properties (those not at the top level of the Properties list) the plugin protocol must be configured to handle these properties by setting the Retrieve Deep Properties or Keep Properties protocol parameter to *. For more information on employing deep properties refer to Accessing deep properties. Exporters Exporter plugins are used to export document data into a downloadable file such as XLSX, PDF, and SD. These protocols offer a large degree of freedom to the protocol developer. The protocol must start with a Plugin Debugging Data Reader component and at some point generate a file that the framework will return to the user. Exporters are available in both the Analyze Visualize and Search Browse areas of the Insight web client. Page 19 BIOVIA Insight Getting Started with Insight Plugins Guide

24 Note: The default Exporter plugins have changed in Insight Exporters developed in previous versions should continue to work but you should develop new plugins using the new framework using the provided template. You can upgrade existing exporters by replacing the Insight Cache Reader with the new Plugin Debugging Data Reader into your exporter protocol and copying the new metadata parameters for the template: Keep Properties Supported Property Types Maximum Exporter template Plugin Debugging Data Reader - allows you to run the custom exporter in the Pipeline Pilot Professional Client for debugging purposes. The Input port must be enabled. Set the Data URI parameter to the value of the Plugin Debugging Data URI for an Insight document (on the Summary tab). Placeholder 1 - replace this with appropriate data processing components to prepare the data for writing. Placeholder 2 - replace this with an appropriate writer component. The Destination parameter should be set to $(JobDir)/$(File Name) so that the exported file is stored appropriately. Exporter plugin help The protocol summary is displayed in the Exporters dialog as follows: Detailed Descriptions of Plugins Page 20

25 The protocol summary and help text are displayed in the Export Options dialog as follows: Pipeline Pilot Insight Insight Help Description The title is the name of the protocol itself The one-line description is the protocol summary The main content is the protocol help This is followed by the standard text: "Select which properties to export for each record." Any protocol-level parameters (apart from those in the Insight Metadata group) are available on the next page of the export options dialog, their help is similarly available in the Insight web client when a parameter is clicked on. Page 21 BIOVIA Insight Getting Started with Insight Plugins Guide

26 Pipeline Pilot Insight Insight Help Description The title is the name of the parameter itself The main content is the parameter help The type and value and other parameter details are not available in the Insight web client. Protocol-level parameters in groups are accessed by the Advanced button on the export options dialog, their parameter help is presented in the same way as the top-level protocol parameters. Exporter plugin protocol rules Create protocol from template Protocol location When creating a new Exporter plugin start with the Export template protocol. This template comes with all required components and sensible parameter defaults. Protocol must be saved in: Protocols/Web Applications/Insight/Exporters/<Category Name> Declare supported data types Accurately declaring supported data types is important because it prevents the Exporter plugin from being enabled for inappropriate document data (chemistry Exporters for records without chemistry data). For more information, see Plugin Categorization and Supported Record Types in this guide. Detailed Descriptions of Plugins Page 22

27 Must contain Use templates when creating an output file name Declare supported property types When run by the framework, records are passed through the main pipeline which must originate with a Plugin Debugging Data Reader component with an open Input port. The protocol must generate one file; this file will be returned to the user. You can use the ${DocumentName} pattern to create a default document name that will match the name of the saved document. See File Name parameter on PDF exporter protocol for an example. Use the Export Metadata > Supported Property Types parameter to limit which column types may be exported by the protocol. String Structure Integer Reaction Double Image Date Label Accessing Deep Properties In order for parameters on the Plugin Options dialog to accept and properly process "deep" properties (those not at the top level of the Properties list) the plugin protocol must be configured to handle these properties by setting the Retrieve Deep Properties or Keep Properties protocol parameter to *. For more information on employing deep properties refer to Accessing deep properties. Page 23 BIOVIA Insight Getting Started with Insight Plugins Guide

28 Chapter 3: Plugin Metadata Widget, Calculator, and Exporter plugins use metadata to control their integration with the Insight web client in two ways: A specially-named protocol-level parameter group Insight Metadata. This exposes metadata to the application which controls various aspects of how the plugin operates within the Insight web client. Per-parameter metadata properties. These control the data available to plugin parameters and the organization of parameters in the Insight web client plugin options dialog. Insight Metadata parameter group Note: Some parameters are only available to users in the Insight/AuthorPlugins group. Tip: For more information on any of these metadata parameters, select the parameter in the Pipeline Pilot client and review the contents of the Help panel. Common Plugin Insight Metadata Parameters Supported Data Types Calculator Plugin Insight Metadata Parameters Retrieve Deep Properties Output Properties Exporter Plugin Insight Metadata Parameters Input User Selection Options Keep Properties Required Properties Supported Data Types Supported Property Types Maximum Output Handling Widget Plugin Insight Metadata Parameters Title Template Retrieve Deep Properties Enable Data Connectivity Selection Single Record Access Client-Side Buffer Size Server-Side Fetch Size Plugin Metadata Page 24

29 Additional Options Developer Mode Launch Config Window Output Images Tip: You can create a Widget, Calculator, or Exporter plugin with all the necessary metadata parameters by using the File New Protocol from Template... option in the Pipeline Pilot client if you are in the Insight/PluginAuthors group. Plugin options and parameter metadata Widget, Calculator, and Exporter plugins share a common method of exposing their protocol-level parameters in the Insight web client. Plugin configuration is handled by the plugin options dialog in Insight. This dialog typically contains Simple and Advanced panels that expose parameters for Insight users to configure the plugin. These correspond to protocol-level parameters on the plugin protocol. Simple panel showing top level parameters Page 25 BIOVIA Insight Getting Started with Insight Plugins Guide

30 Advanced panel showing the non-simple exposed parameters By default, any protocol-level parameters on these plugins are automatically exposed in the Advanced panel of the plugin options dialog. However, for required and other key parameters it is useful to expose these in the Simple panel, which appears first when an Insight user opens the plugin options dialog. Controlling where a parameter appears, what values are available, and how it is validated is accomplished with the use of parameter metadata. Parameter metadata is accessible through the Edit Parameter dialog. To access this, right-click on a parameter in the Pipeline Pilot client and select Edit Parameter..., the select the Metadata tab. Note: Parameter metadata only applies to protocol-level parameters. Plugin Metadata Page 26

31 Define Parameter dialog open to the Metadata tab showing possible metadata keys A parameter may have any number of metadata key-value pairs assigned to it and some metadata attributes may be combined to achieve the desired result. Below is a summary of Insight plugin metadata attributes: Page 27 BIOVIA Insight Getting Started with Insight Plugins Guide

32 Metadata key / Values Description Example Insight_Parameter_Location Simple Pane Only Simple and Advanced Pane Explicitly promotes a parameter to a given location in the plugin options dialog. By default all protocol-level parameters appear in the Advanced panel of the dialog. This allows you to display a parameter on the Simple panel and control whether it also remains in the Advanced panel. Note: If all parameters are on the Simple panel, there is no Advanced panel. Scatter Plot > Symbol Size Insight_Expected_Type Numeric property Generic property Field Tree Format Picker Insight_Allow_Blank True False Determines what data type a parameter expects. For Generic Property or Numeric Property, when set to a value, a dropdown list is displayed, autopopulated with the names of properties in the document with the specified data type. Field Tree will add a property tree to the plugin options dialog with a checkbox at every node. This will send all the checked properties as input to the plugin protocol. Format Picker will provide access to conditional formatting rules on the Widget Options dialog. If no value is set the form field will default to the type of the parameter (StringType, LongType, etc...). Used in conjunction with Expected Type, to render a property populated dropdown that can be blank. Note: An empty value for will be interpreted as "False". Scatter Plot > Data Series 1 X Property Scatter Plot > Symbol Color Pie Chart > Value Property Insight_Allow_Constants True False Used in conjunction with Insight_Expected_Type, to allow constants to be entered into dropdown lists. This allows the user to select a property or to enter a value for the property. Simple Math Calculator > First Operand Note: An empty value for will be interpreted as "False". Insight_Auto_Label_When_Blank True False When true, the plugin options dialog field will have a grayed out label "<auto>" when the field is blank. This is useful when you want to explain to the user that a blank value represents that a default value will be created. Scatter Plot > Data Series 1 Data Options Legend Text Plugin Metadata Page 28

33 Plugin categorization and supported record types Widget, Calculator, and Exporter plugins share a common method of declaring which category they should belong to and what types of data they support. Each plugin is categorized in the Insight web client based on its location in the protocol tree. Protocols Explorer (left) showing exporter plugin protocol paths Exporters dialog (right) for picking exporters in the web client The visibility of plugins in the dialog is controlled by the type of data in the current document and the Supported Data Types protocol-level parameter value. The supported options are: Generic Will be visible and attempt to work for any dataset, but will not deserialize chemistry from the Insight caching system. Molecules Will only be visible for molecular data (root node type) and will fully support chemistry. Generic and Molecules Will always be visible and can work with generic or molecular data types. Page 29 BIOVIA Insight Getting Started with Insight Plugins Guide

34 Chapter 4: Developer Tools This section provides guidance to Pipeline Pilot users who are developing plugin protocols for integration with the Insight web client. Requirements of plugin protocols All plugins must: Have protocol and parameter help - this is available as guidance in the Insight web client as a tooltip or if there are additional protocol parameters displayed in an options dialog. File Adapter plugins must: Have a Source parameter of "URLType" at the top level. Insight will automatically pass the file path to this parameter. Data Generator plugins must: Read in files or generate records in a data format that Insight can accept Widget plugins must: Begin with an Insight Cache Reader component with an open Input port End with an Widget Viewer component Have an Insight Metadata parameter group at the protocol level Calculator plugins must: Begin with an Insight Cache Reader component with an open Input port End with an Insight Cache Writer component Have an Insight Metadata parameter group at the protocol level Exporter plugins must: Have a pipeline starting with an Insight Cache Reader component with an open Input port End with an appropriate Writer component Have an Insight Metadata parameter group at the protocol level Plugin template protocols Protocol templates are provided to simplify the creation of Widget, Calculator, and Exporter plugins. The templates provide all appropriate Insight Metadata settings with sensible defaults along with a skeleton protocol to guide the developer. To create a protocol from template, select File New Protocol from Template... from the menu bar. All the Insight templates are found in the Insight folder of the template root directory. Developer Tools Page 30

35 Useful components Insight Cache Reader This reads data from the Insight cache for processing later in the pipeline of a plugin protocol. When you are developing new plugins it is very useful to supply the Cache ID of a document already present in Insight. To access individual records, specify them in Filter by Records IDs parameter using the Record ID from a Record Inspector widget in the document (you may need to add this widget in the web client to access this information). This and the other Plug-in Debugging group parameters will not have any effect on the records being processed when the Insight Cache Reader receives data from an Insight web client plugin. Insight Cache Writer This updates the Insight cache for the document with the incoming data from previous components in the plugin protocol. Widget Viewer This is used to display the output of a widget plugin in the Insight web client. When a widget plugin protocol is run from Pipeline Pilot Professional Client, this displays the results in an HTML Report Viewer. Convert Range to Maximum This recognizes when a supplied Range contains a maximum value and stores this in a Maximum global property so that it can later be accessed by the Maximum parameter of a reader component in a File Adapter plugin. The MOL SD SDF Reader default File Adapter employs this component. File Adapter Range Filter This filters the incoming data records according to the specified Range so that records before the lower end of the range are removed as well as those after the upper end being excluded by the Maximum parameter on a reader in a File Adapter plugin. Promote and Rename Deep Properties This allows properties from below the top level (that is, sub-level or "deep" properties) to be promoted to the top level so that they can be accessed by subsequent components that work exclusively or primarily with top level properties. This is a simpler strategy than trying to work with sub-level properties directly - which is often not possible at all. Once a protocol employing this promotion has completed, the promoted properties are removed. In some uses the property to promote may be specified along with the name that the property should have at the top level. However, where it is desirable that a user can choose the properties to promote a string-token replacement should be used for Paths to Properties to Promote and New Top-Level Property Names. Create Globals Containing Names This takes the Paths to Properties Providing Names list of deep property paths (for example, "Products/Suppliers/Company Name") and creates corresponding New Global Properties Containing Page 31 BIOVIA Insight Getting Started with Insight Plugins Guide

36 Names whose values are just the names of the provided deep properties (for example, "Company Name"). This allows property names to be preserved when they are promoted to the top level and processed appropriately by later components. This can be used in conjunction with Promote and Rename Deep Properties to create plugins that can handle deep properties specified by a web client user through parameters on plugin options dialogs. Many components provide content that depends on the names of the properties being processed. For example, a Scatter Plot automatically creates axis labels and legends based on the names of the properties being plotted. So for a chart widget that plots user specified deep properties, these need to be promoted to the top level while preserving their names. This component stores the names of the promoted properties in known global properties defined by New Global Properties Containing Names. For example, if Paths to Properties Providing Names is set to: $(Data Series 1 X Property) $(Data Series 1 Y Property) and New Global Properties Containing Names is set to: x y Then you can configure a later Scatter Plot to have X Property set to "$(x)" and Y Property set to "$(y)". This ensures that the selected properties are plotted using the correct names. Moving, renaming, and deprecating plugin protocols Plugin protocols saved with Insight 2.2 or later can be freely renamed or moved around the protocol tree (for example, into subfolders, or from development to production folders) without affecting any previously saved documents or templates that reference those plugins. This is because the plugin reference is based on an internal unique ID in the plugin protocol that is independent of the plugin's name or path. Tip: Protocols should be moved using the Move feature in the Pipeline Pilot Client. Saving the protocol to a different folder will create a new internal ID. Documents and templates created with Insight 2.1 and earlier reference plugin protocols using the protocol path. This means that if a plugin protocol is moved or renamed, some older documents may not display all widgets when opened. Insight's deprecated protocol mapping feature provides the ability to move or rename plugin protocols without breaking older documents and templates. This was developed to support deprecation of some standard plugins shipped with the early versions of Insight. When an older document or template is opened, the referenced widgets and calculators are compared to a list and any references to deprecated (or moved) protocols are replaced with the new protocol path. The DeprecatedMappings.txt file is stored in: <pps_install>/apps/scitegic/insight/public/data/deprecatedmappings.txt You can add one line per protocol to this file with the old protocol path, a tab, then the new protocol path. IMPORTANT! Back up this file after making changes, as it will get replaced during Insight upgrades and you will need to merge your changes into the standard set of changes. Developer Tools Page 32

37 Useful Insight web client tools Document Summary tab All Insight documents contain a Summary tab which publishes information about document contents and sources of data. When the user has Insight/AuthorPlugins or Insight/PackageDeveloper roles the summary tab will reveal further internal information. For all documents it will list a Cache Id which corresponds to the document data's Mongo DB cache. For documents that were created as a result of a query the Results ID (RSID) will be included; a variety of query service components can be used to inspect the contents of the corresponding result set. Page 33 BIOVIA Insight Getting Started with Insight Plugins Guide

38 Record Inspector Widget As long as a developer has the appropriate role, they will see the Record Inspector widget in the Add Widget dialog. When added to a document it allows the developer to see all properties on a given record along with the internal auto-generated Record Id. This record id is the unique identifier used by Insight to identify records within document data. Error Handling In cases where the plugin protocol encounters an error that it cannot recover from it should use the Error() PilotScript method to send a message back to the client. This message will be shown to the user. Developer Tools Page 34

39 Chapter 5: Example Custom Plugins This section describes how to prepare a custom plugin of each type. Tip: You can only create custom plugins in the Pipeline Pilot Professional Client if you are in the Insight/PluginAuthors group. Building a new file adapter plugin This example will demonstrate how to build a file adapter plugin which will allow you to read.xsd files into Insight (.xsd is the Materials Studio structure format). Instructions for Advanced configuration of this custom file adapter can be used to limit the structures read in to non-periodics only. Requirement: You must have the Materials Studio Collection installed to develop this example plugin protocol. 1. Open a new protocol in the Pipeline Pilot client. 2. Add a Material Reader component. 3. Promote the Source parameter to the protocol level (unchecking the Promote entire group checkbox). 4. Click in the empty space in the protocol window to check that the Source parameter is available at the protocol level. 5. Select the Source parameter and ensure that its Parameter Type in the Help window is "URLType". 6. Add a Material to Molecule converter component - this will make the output generated more compatible with data from other sources. 7. Add a File Adapter Range Filter component and promote its Range parameter. 8. In the Help window for the protocol, right-click and select Edit Help Text... Enter: Provides read access to Materials Studio XSD, XTD, and XOD files 9. Save the protocol as XSD XTD XOD Reader in the Web Applications\Insight\File Adapters\Custom folder. Example custom plugins Page 35

40 10. To test your protocol, open the Insight web client and select File in the Import Data From section of the Home Page. Navigate to and select a Materials Studio XSD file, click Open. 11. The Import Preview will show you the contents of the XSD file. Click Finish to load this into a new document. Tip: You can use the Combine Data functionality to merge multiple documents containing single structures. Advanced configuration The file types that can be read by the Material Reader can represent 3D and 2D periodic structures as well as 0D discrete molecules. The simple protocol above will not handle these structures well and will directly report component error messages to the end user. You can enhance this protocol to provide better error reporting and filtering of unsuitable records if the input file contains a mixture of 0D, 2D, and 3D structures. 1. After the Material Reader, add a Periodicity (Materials) component followed by a Property Range Filter. 2. On the Property Range Filter set the Property Name to "Periodicity" and the Value Range List to "0D". 3. After the Property Range Filter add a Custom Manipulator (PilotScript) component and set the Expression := true; This creates a Global Property named structures with a value of "true" to indicate that at least one record has passed through the Property Range Filter with a Periodicity of "0D". 4. Rename this Custom Manipulator (PilotScript) to Structures Generated? to indicate its purpose. 5. At the fail port of the Property Range Filter component, connect another Custom Manipulator (PilotScript)and set the Expression := "This input file only contains periodic structures which cannot be imported into Insight."; This both identifies that at least one record has passed through the Property Range Filter with a Periodicity value different from "0D" and sets an error message to return to the Insight web client when all records fail this property value check. 6. Rename this Custom Manipulator (PilotScript) to Report Error? to indicate its purpose and close its Pass port. 7. In a new pipeline add a Custom Manipulator (PilotScript) and close both its Input and Pass ports. 8. Set the Expression to: is not defined then is defined then error(@error); else error('no records generated.'); end if; end if; This checks whether any structures were 0D and if there were none it checks for any errors. If the error message has already been set this is employed and if not a general failure message is created. Page 36 BIOVIA Insight Getting Started with Insight Plugins Guide

41 These error messages are returned to the Insight web client. See Error Handling for more information. 9. Rename this Custom Manipulator (PilotScript) to If no structures report error to indicate its purpose. 10. Save the protocol. Tip: You could also add Material-specific calculator components before the Material to Molecule converter to add extra properties to the data before importing it. Building a new data generator plugin This example will demonstrate how to build a data generator plugin which will allow you to read create a document containing pre-defined data. Instructions for Advanced configuration of this custom data generator can be used to provide greater flexibility and control over the data generated from the Insight web client. 1. Open a new protocol in the Pipeline Pilot client. 2. Add a SD Reader to put some structures on the pipeline. 3. Click the... for the Source parameter and navigate to Chemistry Data\AminoAcids, select all the.mol files and click Select. 4. Add the following calculator components: ALogP pka Molecular Formula Molecular Weight Num H Acceptor Donors 5. For Molecular Formula choose to output "Molecular Composition" as well as the default. Example custom plugins Page 37

42 6. In the Help window for the protocol, right-click and select Edit Help Text... Enter: Creates a document containing the 20 standard amino acids and calculates some basic properties for them 7. Save the protocol as Amino Acid Properties Generator in the Web Applications\Insight\Data Generators folder. 8. To test your protocol, open the Insight web client and select Data Generator... in the Import Data From section of the Home Page. Select the Amino Acid Properties Generator generator. 9. The Import Preview will show you the amino acids and their properties. Click Finish to load this into a new document. Advanced configuration In order to provide greater flexibility and control over the data generated in the Insight web client you can promote some parameters to the protocol level. 1. In the protocol you just created, select the ALogP component. Promote both properties to the protocol, renaming the Output parameter to ALogP Output. 2. Open the Edit Protocol dialog and create a new parameter named ALogP with Parameter type set to "GroupType". Drag and drop the ALogP Output and Atom Properties Output parameters into the new group. 3. Repeat these steps to promote some or all parameters from each of the calculator components, naming and grouping them so that end-users will know what they control, for example: 4. Review the parameter help for all protocol parameters, ensure that it is suitable for Insight web client users. 5. Save the protocol in the Web Applications\Insight\Data Generators folder, the promoted Page 38 BIOVIA Insight Getting Started with Insight Plugins Guide

43 parameters will now be available (with help as tooltips) in the Insight web client. Building a new widget plugin This example will demonstrate how to build a widget plugin which will allow you to add a box plot to a document. Instructions for Advanced configuration of this custom widget can be used to automatically link parameters to available document properties. 1. Open the Pipeline Pilot Professional Client. 2. Select File New Protocol from Template... from the menu bar. 3. Open the Insight folder and double-click on the Widget template. 4. Read and then delete all the sticky notes. 5. Add a Box Plot before the Widget Viewer and delete the Placeholder component. 6. Select the Box Plot component, right-click the X Property parameter, choose Promote... from the shortcut menu. 7. On the Promote Parameter to Parent dialog, delete Data Series 1 from the name of the promoted parameter and click OK. 8. Repeat this for the Y Property parameter, again removing the Data Series 1 prefix from the promoted parameter name. 9. Add a Sort on Property after the Insight Cache Reader and delete the generic Placeholder component. 10. Select the Sort on Property component and right-click the Sort Order parameter, choose Promote... from the shortcut menu. Click OK on the Promote Parameter to Parent dialog. Example custom plugins Page 39

44 11. Right-click the Property Name parameter and choose Promote... from the shortcut menu. 12. Select "X Property" in the Promote Parameter to Parent dialog. The sorting will be performed on the same property as used for the X data in the box plot generated. Click OK. 13. On the protocol, set the Title Template parameter to: ${Param:Y Property} vs. ${Param:X Property} This will automatically generate the title based on the X and Y properties specified in the Insight web client. 14. In the Help window for the protocol, right-click and select Edit Help Text... Enter a Summary: Creates a box plot for the specified X and Y properties And a Description: Use this widget to add a plot to your document that represents data points as boxes with whiskers on a chart. 15. To test your protocol, open a document in Insight. On the Summary tab, find and copy the Cache Id. 16. Select the Insight Cache Reader and paste the document's Cache Id into the Cache ID parameter. Specify values for the X Property and Y Property protocol parameters according to the data in the document. 17. Run the protocol. 18. When you are satisfied with the behavior of the protocol, remove the values for the Cache ID and the X Property and Y Property protocol parameters. 19. Save the protocol in the Web Applications\Insight\Widgets folder, the promoted parameters will now be available (with help) in the Insight web client. Note: In addition to the Sort Order, X Property, and Y Property protocol parameters this template automatically adds the Title Template parameter to the Widget Options dialog. Page 40 BIOVIA Insight Getting Started with Insight Plugins Guide

45 Advanced configuration In the simple initial set up of this widget, the X and Y properties are text fields and the end user must manually enter exactly the right name for a document property. You can perform some extra configuration on these protocol parameters to automatically link them to available document properties. You can also choose to customize the display of some protocol parameters in the Advanced section of the Widget Options dialog. Tip: See Plugin Options for more information on how to configure parameter metadata. 1. In the protocol you just created, select the X Property parameter, right-click and select Edit Parameter... from the shortcut menu. 2. Select the Metadata tab on the Edit Parameter dialog. 3. Click to add a new metadata item. 4. Choose Insight_Expected_Type from the dropdown list and set the value to "Generic Property". For widget parameters which require numeric data you should set the Insight_Expected_Type to "Numeric Property", this will limit the properties available in the Insight web client to exclude strings. 5. Click, choose Insight_Parameter_Location from the dropdown list and set the value to "Simple Pane Only". Click OK. 6. Repeat this for the Y Property parameter. If any protocol parameters have their location metadata set to "Simple Pane Only" all other protocol parameters will be excluded from the Simple section of the Widget Options dialog. In this example, placing X Property and Y Property in the Simple section will force Sort Order and Title Template into the Advanced section. 7. Save the protocol. The Widget Options dialog now displays only the X Property and Y Property parameters in the default view, these are now both available as dropdown lists automatically populated with the names of the properties in the document. Example custom plugins Page 41

46 Accessing deep properties In order for parameters on the Widget Options dialog to access "deep" properties (those not at the top level of the Properties list) and for later components to handle these, the widget plugin protocol must be configured to handle these properties. For more information on employing deep properties refer to Accessing deep properties. To add deep property handling to this example: 1. In the protocol-level Insight Metadata parameter group, set the Retrieve Deep Properties parameter to "*" so that the protocol can access any deep properties. 2. Add a Create Globals Containing Names component in a first pipeline, before the existing one. 3. Set the Paths to Properties to Providing Names parameter to: $(X Property) $(Y Property) 4. Set the New Global Properties Containing Names parameter to: x y 5. Add a Promote and Rename Deep Properties component after the Insight Cache Reader. 6. Set Paths to Properties to Promote parameter to: $(X Property) $(Y Property) 7. Set the new Top-Level Property Names parameter to: $(x) $(y) 8. On the Box Plot component, right-click the X Property parameter and choose Edit Parameter... from the shortcut menu. 9. Change the Parameter type to StringType and click the OK button. Change the parameter's value to $(x). 10. Repeat this for the Y Property parameter on the Box Plot component, again changing the parameter type and setting its value to $(y). This sets up the transfer of the properties specified in the protocol-level X Property and Y Property parameters to the x and y global properties and then uses these global properties in the box plot configuration rather than the full deep property path which cannot be processed by the Box Plot component. The end user will not experience any change in the presentation of this widget after deep properties are configured, but the widget will be able to handle a wider range of input properties. Page 42 BIOVIA Insight Getting Started with Insight Plugins Guide

47 Building a new calculator plugin This example will demonstrate how to build a calculator plugin which will allow you to use data in your document to calculate absorption, distribution, metabolism, and excretion-toxicity (ADMET) properties. 1. Open the Pipeline Pilot Professional Client. 2. Select File New Protocol from Template... from the menu bar. 3. Open the Insight folder and double-click on the Calculator template. 4. Read and then delete all the sticky notes. 5. Add an ADMET All Models component after the Insight Cache Reader and delete the placeholder component. 6. Select ADMET All Models, right-click on the Output parameter group and select Promote (ensuring the entire group is promoted). 7. In the promotion dialog, give the parameter a new name "Properties to Calculate" and select the "Promote entire group" checkbox. It is important to not have top level parameters called Output, because it becomes a calculable property in Pilot Script and you might accidentally overwrite the functionality of an existing calculable property on the system. 8. Right-click the Output parameter group on the protocol and select Edit Parameter Select the Metadata tab, and add an Insight_Parameter_Location metadata key. Set the value to "Simple and Advanced Pane". Click OK. This will display the Output parameter on the Simple panel of the Run Calculation dialog and the grouped parameters on the Advanced panel. 10. Select all options for the Output parameter. This ensures that all options are checked by default in the Insight web client. 11. Set the Supported Data Types to "Molecules" in the Insight Metadata parameter group on the protocol as the ADMET All Models can only take molecules as input. 12. For the Output Properties parameter, enter the following: ADMET_Absorption_Level ADMET_BBB_Level ADMET_BBB ADMET_Solubility_Level ADMET_Solubility These are all the properties that can be generated by ADMET All Models. Enabling all properties will ensure that whatever is produced is returned to the document. If any generated properties are not listed they will never be returned to the document whether they are generated or not. 13. In the Help window for the protocol, right-click and select Edit Help Text... Enter a Summary: Calculates all ADMET properties And a Description: Use this calculator to choose which ADMET properties (aqueous solubility, blood brain barrier, and intestinal absorption) are computed and added to the document. 14. To test your protocol, open a document in Insight. On the Summary tab, find and copy the Cache Id. 15. Select the Insight Cache Reader and paste the document's Cache Id into the Cache ID parameter. Example custom plugins Page 43

48 Run the protocol. 16. When you are satisfied with the behavior of the protocol, remove the value for the Cache ID. 17. Save the protocol in the Web Applications\Insight\Calculators\Chemistry folder, the promoted parameters will now be available (with help) in the Insight web client. Page 44 BIOVIA Insight Getting Started with Insight Plugins Guide

49 Building a new exporter plugin This example will demonstrate how to build an exporter plugin which will allow you to generate an XML file containing the data from the current document. 1. Open the Pipeline Pilot Professional Client. 2. Select File New Protocol from Template... from the menu bar. 3. Open the Insight folder and double-click on the Export template. 4. Read and then delete all the sticky notes and the placeholder components. 5. In order to export unsaved documents you should create a name for them to use: a. Add a Custom Manipulator (PilotScript) without connecting it to the Plugin Debugging Data Reader. Close the Input, Fail, and Pass ports and move this into an initial pipeline. b. Set the Expression to: Name' is defined then Name' rlike('\$\{documentname\}') Name':=RSubst(@'File Name','\$\{DocumentName\}','New Doc'); end if; end if; c. Change the component name to "File name for unsaved documents". 6. Add an XML Writer (SciTegic) after the Plugin Debugging Data Reader. 7. Set the Destination to "$(JobDir)/$(File Name)". 8. Insert a Molecule to CTAB between the reader and writer components. These will convert the structure to CTAB format so that is accessible to other applications from the generated XML. 9. Insert a Remove Properties after the Molecule to CTAB and set PropertyList to "Molecule". This will remove the converted structure from the record to prevent duplication of the information being stored. 10. For the protocol File Name parameter, change the "suffix" to "xml". 11. In the Help window for the protocol, right-click and select Edit Help Text... Enter a Summary: Exports data in XML format And a Description: Generates an XML file containing all the records in the current document. 12. To test your protocol, open a document in Insight. On the Summary tab, find and copy the Plugin Debugging Data URI. Note: If you are using BIOVIA Search without an Insight license the Plugin Debugging Data URI can be found in the lower toolbar beneath a browse form or table of search results. For example: 13. Select the Plugin Debugging Data Reader and paste the document's Plugin Debugging Data URI into the Data URI parameter. Run the protocol. Building a new exporter plugin Page 45

50 14. When you are satisfied with the behavior of the protocol, remove the value for the Data URI. 15. Save the protocol in the Web Applications\Insight\Exporters folder, the promoted parameters will now be available (with help) in the Insight web client. Page 46 BIOVIA Insight Getting Started with Insight Plugins Guide