biovia insight: getting started with insight...

GETTING STARTED WITH INSIGHTPLUGINS GUIDEBIOVIA INSIGHT 2018

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 arecommercial 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 DassaultSystè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 BIOVIAsoftware, acknowledge the source in an appropriate format. For example:

"Computational results obtained using software programs from Dassault Systèmes BIOVIA. The abinitio calculations were performed with the DMol3 program, and graphical displays generated withBIOVIA Insight."

BIOVIAmay grant permission to republish or reprint its copyrighted materials. Requests should besubmitted to BIOVIA Support, either through electronic mail to [email protected], or in writingto:

BIOVIA Support5005Wateridge Vista Drive, San Diego, CA 92121 USA

ContentsChapter 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 ViewMode 14

Conditional formatting 14

Title Template 15



Calculators 15

Calculator template 16

Calculator plugin help 16

Calculator plugin protocol rules 18


Exporters 19

BIOVIA Insight • Getting Started with Insight Plugins Guide | Page i

Exporter template 20

Exporter plugin help 20

Exporter plugin protocol rules 22


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 CacheWriter 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


Building a newwidget plugin 39


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

Chapter 1:IntroductionIn 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, themajority ofthe default functionality in Insight is built using plugins.Users in the Insight/PluginAuthors group can develop custom plugins by creating Pipeline Pilotprotocols. Plugin protocols can use the full range of generic, scientific, reporting, and other componentsavailable in Pipeline Pilot to provide their functionality.The types of plugins that are available are:

Plugin Type Description Insight Availability

File Adapters Protocols that load data from files.These can also customize the behavior of an already-supported file type.

Load data from fileHome Page:Import Data From | FileDocument toolbar:Import Data | File...

DataGenerators

Protocols that load arbitrary data into Insight.Themost powerful data import extension, makingany data that can be put on a Pipeline Pilot datarecord available to the application.

Load data from another sourceHome Page:Import Data From | DataGeneratorDocument toolbar:Import Data | DataGenerator...

Widgets Protocols that use reporting components togenerate visualizations of document data.In the Insight web client, Widgets are placed intodrag-and-drop panels on a tab.Widget plugins are saved and stored in users'documents and templates. Each application of anywidget can be configured and customizedindividually.

Provide data visualization:Document toolbar:Add Widgets

The Add Widget dialog onlydisplays widgets appropriate tothe current data record types.

Introduction | Page 1

Plugin Type Description Insight Availability

Calculators Protocols that generate or manipulate properties inthe document data.

Provide data manipulationDocument toolbar:Calculate

The Run Calculator dialog onlydisplays calculators appropriateto the current data recordtypes.

Exporters Protocols that handle the output of data fromInsight.These can create files, reports, or save data intoother repositories such as databases.By default, Exporter protocols are aware ofdocument selection and filter state.

Export data for sharingDocument toolbar:Export

The Export dialog only displaysexporters appropriate to thecurrent data record types.

Template and example plugins are available in Insight to guide you and to make creation of new pluginseasy. Plugins are all always stored in the "Protocols/Web Applications/Insight" folder in the PipelinePilot Professional Client in a subfolder appropriate to the type of plugin protocol and the web clientfunctionality.

Tip: Always begin development of a custom plugin by loading a template. Press CTRL + SHIFT + N orchoose File | New Protocol from Template ... in the Pipeline Pilot Professional Client to viewavailable templates.

PermissionsPlugin 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:

http://<server>:<port>/adminwhere <server> and <port> are the name of themachine where your Pipeline Pilot server is installedand 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 theSummary tab for a Document in the Insight web client:

Cache IdData TypesNode Type

Page 2 | BIOVIA Insight • Getting Started with Insight Plugins Guide

Additional InformationFor more information about Insight and other BIOVIA software products, visit BIOVIA Support on theWeb: https://community.3dsbiovia.com

Introduction | Page 3

https://community.3dsbiovia.com/

Chapter 2:Detailed Descriptions of Plugins

Data GeneratorsWidgetsCalculatorsExporters

The data types suitable for a plugin in the Insight web client are determined by the value of theSupported 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 toextend the list of Legal Values.

Note: Refer to the Plugin Metadata section for more information on the Supported Data Typesparameter.

Tip: For each plugin category you should save your custom plugins in a subfolder (a new subfolder ifnecessary). These subfolders are displayed in the Insight web client plugin selection dialogs and assistusers in categorizing and sorting.

Accessing Deep PropertiesThe Exporter, Calculator, andWidget plugins can access "deep" properties (those not at the top level ofthe 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 deepproperties, their names, and their values throughout a plugin protocol:

Promote and Rename Deep Properties promotes deep properties to top level arraysCreate 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 pluginprotocol:

In the protocol-level Insight Metadata parameter group, set the Retrieve Deep Properties or KeepProperties 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 andRename Deep Properties with these parameter settings

Paths to Properties to Promote should reference the protocol-level parameters (exposed asoptions 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 theNewGlobal Properties Containing Names parameter on the initial Create Globals Containing Namescomponent.Subsequent components which process deep properties should use the global property namesgenerated by theNew Top-Level Property Names parameter rather than the protocol-levelparameters' names (unless a Create Globals Containing Names is also used in which case theglobal properties must be employed instead).

Detailed Descriptions of Plugins | Page 4

For plugins which use property names in later components (for example, widgets), the firstcomponent in an initial pipeline should be Create Globals Containing Names with these parametersettings:

Paths to Properties Providing Names should reference the protocol-level parameters (exposed asoptions on the plugin dialog) which should be able to accept deep properties.NewGlobal Properties Containing Names should contain the same number of values as Pathsto Properties Providing Names with the new global names supplied in the same order as the deepproperties being loaded.Subsequent components which process deep properties should use the global property namesgenerated by theNewGlobal Properties Containing Names parameter rather than the protocol-level parameters' names.

When plugin protocols are configured to access deep properties in this way web client users can drag-and-drop items from the Properties list into the appropriate plugin parameters on a plugin optionsdialog.

Tips:The instructions in Building a newwidget plugin include configuration of deep properties handling.The IC50 Plot Examplewidget protocol is available to users in the Insight/AuthorPlugins group (inthe Insight/Widgets/Development directory) and employs the Create Globals Containing Namesand Promote and Rename Deep Properties components with a Scatter Plot.TheDeep Property Average Calculator protocol is available to users in the Insight/AuthorPluginsgroup (in the Insight/Calculators/Development directory) and employs the Promote and RenameDeep Properties component with a Basic Statistics for Each Data calculator.

Plugin help in the Insight web clientPlugins provide the opportunity for Insight web clients to enter values, settings, or specify parameteroptions. To ensure that the Insight web client help for plugins is useful and informative for you shouldensure that all plugin protocols have protocol help and all protocol-level parameters have help whichdescribes how to use the parameter from the perspective of the Insight web client.


Good practice in preparing plugin helpTip Details

Provide adequatedetails

Include all information that helps Insight web client users understand how towork with this custom plugin.

Use a minimalist style Be concise. Omit needless words. Avoid phrases such as “this exporter” toreduce wordiness.For example:

No need to say "This calculator performs…".Instead, just say, "Performs…".

Talk to your reader ifnecessary as "you"

Use first person singular ("you" instead of "the user")

Do not leave thedescription blank

No plugin protocol or parameter is too simple for a basic description.

Do not use PipelinePilot terminology

Insight web client users will not know anything about protocols andcomponents. Refer to the plugin instead. The plugin configuration fieldsshould be referred to as parameters.Do not refer to components or include Pipeline Pilot links to relatedcomponents.

For lists of parametervalues and theirdescriptions usebullets

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>

Format references toother parameters

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 SizeThe size of the Chemistry Image column, in percentage points.

Make references toparameter values clear

Use quotes around values, for example:OrientationSpecifies how the document is positioned on the page. "Portrait"positions the print vertically; "Landscape" positions it horizontally.

Do not includehyperlinks for protocolhelp

Links will appear as underlined text but web client users cannot click on thecontents of tooltips.

Do not mentionPilotScript

Insight web client users won't knowwhat this is or have the opportunity touse it.


File AdaptersFile Adapters are available in the Insight web client through the Import Data from File function (either onthe home page or in an open document).File Adapters plugins are protocols that include a file reader component and are used to read data froma given file type into Insight. The name of the File Adapter protocol is used to determine which file typesit can read. For example, the File Adapter that reads delimited text files is called the CSV TSV TXT Readerand 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 helpAny protocol-level parameters are available in the Import Preview, their help is similarly available in theInsight web client when the cursor is placed over a parameter.

Pipeline Pilot

Insight

Insight HelpDescription

The content is the parameter helpThe type and value and other parameter details are not available in theInsight web client.

Protocol-level parameters in groups are displayed in group boxes in the Settings panel.


File Adapter plugin protocol rulesProtocoltermination

The protocol must terminate with at least one open pass port.

Protocolname

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 ofMOL SD SDF Readerwould be registered asthe reader for files ending with .sd, .mol, and .sdf. Compressed files are automaticallyexpanded before the file name extension is evaluated.

Protocollocation

Protocol must be saved in:Protocols/Web Applications/Insight/File Adapters/Custom

If the file typemappings clash with the default Insight File Adapters those in /Custom willtake precedence.

Protocolparameters

All File Adapter plugin protocols must have a Source parameter of "URLType" at the toplevel. Insight will automatically pass the path to the selected file to this parameter.

Ranges To allow users to specify a range of records to import you should include a ConvertRange to Maximum at the beginning of the File Adapter protocol and promote theRange to the protocol level. Then add a File Adapter Range Filter after the readercomponent, promoting and merging its Range parameter with the one already on theprotocol. Then set theMaximum parameter on the reader component to $(Maximum)so that it uses themaximum value identified by the Convert Range to Maximum.

Data GeneratorsData Generators are a more abstract form of File Adapter plugins. A data generator is any protocol thatretrieves or creates data for Insight. This makes Data Generators ideal for pulling data from webservices, instruments, and other creative sources, including online sources.

Data Generator plugin protocol rulesProtocoltermination


Protocollocation

Protocol must be saved in:Protocols/Web Applications/Insight/Data Generators/<CategoryName>

Protocolparameters

There are no requirements regarding plugin protocol parameters. It is a good idea toprovide sensible defaults for any parameters that you expose because Insight willattempt to run the protocol with defaults when the user selects it from the Load fromData Generator dialog. The default preview that the user will get will be based on thedefault settings. To prevent default preview you can expose at least one parameterwithout a value.

Restrictions Data Generators should not include any Reporting Collection components.


Accessory protocolsA data generator protocol can also call another protocol to provide the dynamically generated data, forexample 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 (adropdown 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 asmergeme) which will result in an array ofvalues (usingMerge Properties) and then keeps only the property that you want (using KeepProperties).Creates a global property (such as AssayNames, using a Custom Manipulator (PilotScript)) tohold 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-levelParameters.

4. In the Parameters window of the accessory protocol, choose theWeb Service tab:

5. In the Results area, click Edit....6. 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 theWeb 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 accessoryprotocol at this point, you might need to close and reopen it first before re-testing.


Data Generator plugin helpThe 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 theImport Preview, their help is similarly available in the Insight web client when the cursor is placed over aparameter.

Pipeline Pilot

Insight


The content is the parameter helpThe type and value and other parameter details are not available in theInsight web client.


Protocol-level parameters in groups are displayed in group boxes in the Settings panel.

Data Generator plugin protocol rulesProtocoltermination


Protocollocation

Protocol must be saved in:Protocols/Web Applications/Insight/Data Generators/<CategoryName>

Protocolparameters

There are no requirements regarding plugin protocol parameters. It is a good idea toprovide sensible defaults for any parameters that you expose because Insight willattempt to run the protocol with defaults when the user selects it from the Load fromData Generator dialog. The default preview that the user will get will be based on thedefault settings. To prevent default preview you can expose at least one parameterwithout a value.

Restrictions Data Generators should not include any Reporting Collection components.

WidgetsWidget plugin protocols are wrappers for reports generated with the use of Pipeline Pilot ReportingCollection. Because customWidget plugins use the same framework as standard Insight widgets theyhave 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 inresponse to application events.

Widget template

Insight Cache Reader - allows you to run the custom widget in the Pipeline Pilot Professional Clientfor debugging purposes. The Input port must be enabled.Placeholder 1 - replace this with appropriate data processing components to prepare the data forwriting.Placeholder 2 - replace this with an appropriate writer component. TheDestination parameter shouldbe 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 modeThe Additional Options group of Insight Metadata parameters for widgets contains a Developer Modeparameter.When this is set to "True", Insight runs the widget in developer mode - a refresh button is added to thewidget toolbar that its contents can be refreshed on-demand, dynamically updating its contents as the


underlying plugin protocol is developed. In this mode the widget options dialog will be refreshed everytime 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 seeprotocol changes.

Widget plugin helpThe 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 itselfThe one-line description is the protocol summaryThemain content is the protocol helpThis 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 thenext page of the widget options dialog, their help is similarly available in the Insight web client when aparameter is clicked on.


Pipeline Pilot

Insight


The title is the name of the parameter itselfThemain content is the parameter helpThe type and value and other parameter details are not available in theInsight 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 sameway as the top-level protocol parameters.

Widget plugin protocol rulesCreateProtocolfromTemplate

When creating a newwidget plugin, start with the Insight Widget template protocol.This template comes with all the required components and appropriate parameterdefaults. This template comes with all required components and sensible parameterdefaults.

Protocollocation

Protocol must be saved in:Protocols/Web Applications/Insight/Widgets/<Category Name>

Declaresupporteddata types

Accurately declaring support data types is important because it prevents theWidgetplugin from being enabled for inappropriate document data (chemistry Widgets forrecords without chemistry data). For more information, see Plugin Categorization andSupported Record Types in this guide.


MustContain

When run by the framework, records are passed through themain pipeline, which mustoriginate with an Insight Cache Reader component that contains an open Input port.This main pipelinemust terminate in aWidget Viewer component.You can have some initialization components and some cleanup components but makesure that only one pipeline has an Input port and it starts with the Insight CacheReader.

ComponentbeforeWidgetViewer

Data records should flow into at least one Reporting component before arriving attheWidget Viewer component.If the component immediately upstream ofWidget Viewer is an interactive chart(Scatter Plot, Bar Chart, Histogram, Line Chart, Radar Chart) then it will beembedded into the document layout as an image that is automatically resized withthe layout.All other reporting components will be embedded into the document inside anIFRAME element.

Let Insightmanage thelayout ofcharts

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 theautomatic chart resizing. Instead you’ll get fixed-size charts in a dynamically resizedcontainer.

Widgets advanced optionsData ConnectorWidget plugins use Reporting Collection’s Data Connector component to communicate record selectionwith Insight and other widgets in the document. This feature is automatically configured by Insight withsensible defaults that should be appropriate for most widgets. TheData Connector functionality isactivated by the True/False setting of the Enable Data Connectivity parameter on the Insight CacheReader component.

Single Record View ModeBy default,Widget plugins are record aggregators, meaning that they collect all records passed to themand generate a combined report or chart. Scatter Plot, Histogram, and Table are all examples of widgetsthat aggregate records into a single report.Insight can also run widgets in a Single Record View (SRV)modewhere a report is generated for eachrecord. Insight then adds a paging toolbar that allows the user to page through the records. TheDetailView and theMolecule Viewerwidgets are examples of widgets running in SRVmode.SRV mode is controlled by the Single Record Access parameter in the Insight Metadata group. WhenSingle Record Access is "True", the two parameters in this group are enabled. The defaults for theseshould work for most Widgets.Internally, when Insight runs a widget protocol in SRVmode it will do so in RunToCompletionmode foreach data record. All components in the widget protocol are executed for each data record passed intothe protocol. Any initialization and/or finalization pipelines are also executed for each record.

Conditional formattingTo enable a feature of you widget to benefit from conditional formatting you should add a Color byFormatting Rule component to your widget protocol, before any reporting components. Promote theFormat parameter so that it will be available on theWidget Options dialog (changing the name of thepromoted parameter appropriately). Set the Color parameter on the component to the property name


that should contain the color specified by the rule. On the reporting component which should use thisrule, set the appropriate parameter value to the same property name.For example, the Scatter Plotwidget protocol uses the Color property on both the Color parameter ofColor by Formatting Rule and the Symbol Color parameters on both Scatter Plot reportingcomponents.

Title TemplateWidget plugin protocols can provide a template that is used to construct the title of the widget panel inthe Insight web client.This is controlled by the Title Template parameter in the Insight Metadata parameter group on theprotocol. This supports patterns that are substituted for protocol name, document name, or the valueof a particular parameter. For example a Scatter Plotmight 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 titlesuch as “ALogP vs. Molecular Weight”.

Accessing Deep PropertiesIn 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 theseproperties by setting the Retrieve Deep Properties or Keep Properties protocol parameter to *.For more information on employing deep properties refer to Accessing deep properties.


CalculatorsCalculator plugins are able to add and manipulate properties on records in document data. These datachanges are persisted when the document is saved. Calculators can take all records in a document asinput, or only a selected subset of records.All Calculator protocols have an Insight CacheWriter component. During development of a customwidget this component provides a preview of data as it would be written to the data cache. When runthrough the web client, this component will save the records in the document.


Calculator template

Insight Cache Reader - allows you to run the custom calculator in the Pipeline Pilot Professional Clientfor debugging purposes. The Input port must be enabled.Placeholder - replace this with calculation components. Promote any configuration parameters fromthis component or subprotocol to the top level to generate a configuration form in an options dialogfor the calculator in the Insight web client.Insight CacheWriter - updates the data and metadata caches with the calculated properties andupdates the data descriptor object that is returned to the Insight web client.

Calculator plugin helpThe 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:


PipelinePilot

Insight

InsightHelpDescription

The title is the name of the protocol itselfThe one-line description is the protocol summaryThemain content is the protocol helpThis 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 thenext page of the calculator options dialog, their help is similarly available in the Insight web client when aparameter is clicked on.


Pipeline Pilot

Insight



Protocol-level parameters in groups are accessed by the Advanced button on the calculate optionsdialog, their parameter help is presented in the sameway as the top-level protocol parameters.

Calculator plugin protocol rulesCreateprotocol fromtemplate

When creating a new calculator plugin start with the Insight Calculator templateprotocol. This template comes with all required components and sensible parameterdefaults.

Don’tmanipulatechemistry

Calculator plugins should not create or manipulate chemistry on the records thatpass through them. This functionality isn’t currently supported and may corruptdocument data.

Don’t create ormanipulatedeepproperties

Calculated properties must be on the top-level of the record.

Reportprogress

Some calculators have to do a lot of up front work before they can begin processingany records (for example, those that generatemathematical models). For thesecalculators it can appear to the end user that the calculator is not progressing.To provide information on calculators' progress during initialization you can sendmessages to the user's browser using the SendMessageToClient() PilotScriptfunction.

Protocollocation

Protocol must be saved in:Protocols/Web Applications/Insight/Calculators/<Category Name>



Accurately declaring supported data types is important because it prevents theCalculator 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 Typessection in this guide.

Declare outputproperties onthe protocol

The Insight Metadata > Output Properties parameter is used by the framework toidentify which properties are being added or modified by the calculator. All otherproperties are stripped off before the records are persisted so you must either setthe protocol-level parameter or set it dynamically in the protocol.Example of static use:

ALogPExamples of dynamic use:

Simple MathMolecular Properties

Do not declarea parametercalled Outputon yourprotocol

When a protocol declares a top level parameter called Output, it becomes acalculable property available in Pilot Script. Insight calculators do not support beingused as calculable properties. More importantly, you might accidentally overwritethe functionality of an existing calculable property on the system.

Must contain When run from the web client, records are passed through themain pipeline. Thismust begin with an Insight Cache Reader component with an open Input port.This main pipelinemust terminate in a Insight CacheWriter component.

Restrictions Calculators should not include any Reporting Collection components.


ExportersExporter 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 witha Plugin Debugging Data Reader component and at some point generate a file that the framework willreturn to the user.Exporters are available in both the Analyze Visualize and Search Browse areas of the Insight web client.


Note: The default Exporter plugins have changed in Insight 2018. Exporters developed in previousversions should continue to work but you should develop new plugins using the new frameworkusing the provided template.You can upgrade existing exporters by replacing the Insight Cache Readerwith the new PluginDebugging Data Reader into your exporter protocol and copying the newmetadata parameters forthe template:

Keep PropertiesSupported Property TypesMaximum

Exporter template

Plugin Debugging Data Reader - allows you to run the custom exporter in the Pipeline PilotProfessional Client for debugging purposes. The Input port must be enabled.

Set theData URI parameter to the value of the Plugin Debugging Data URI for an Insightdocument (on the Summary tab).

Placeholder 1 - replace this with appropriate data processing components to prepare the data forwriting.Placeholder 2 - replace this with an appropriate writer component. TheDestination parameter shouldbe set to $(JobDir)/$(File Name) so that the exported file is stored appropriately.

Exporter plugin helpThe protocol summary is displayed in the Exporters dialog as follows:


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 itselfThe one-line description is the protocol summaryThemain content is the protocol helpThis 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 thenext page of the export options dialog, their help is similarly available in the Insight web client when aparameter is clicked on.


Pipeline Pilot

Insight



Protocol-level parameters in groups are accessed by the Advanced button on the export options dialog,their parameter help is presented in the sameway as the top-level protocol parameters.

Exporter plugin protocol rulesCreateprotocolfromtemplate

When creating a new Exporter plugin start with the Export template protocol. Thistemplate comes with all required components and sensible parameter defaults.

Protocollocation

Protocol must be saved in:Protocols/Web Applications/Insight/Exporters/<Category Name>


Accurately declaring supported data types is important because it prevents theExporter plugin from being enabled for inappropriate document data (chemistryExporters for records without chemistry data). For more information, see PluginCategorization and Supported Record Types in this guide.


Mustcontain

When run by the framework, records are passed through themain pipeline which mustoriginate 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.

Usetemplateswhencreating anoutput filename

You can use the ${DocumentName} pattern to create a default document name thatwill match the name of the saved document.See File Name parameter on PDF exporter protocol for an example.

Declaresupportedpropertytypes

Use the Export Metadata > Supported Property Types parameter to limit which columntypes may be exported by the protocol.

StringIntegerDoubleDate

StructureReactionImageLabel



Chapter 3:Plugin MetadataWidget, Calculator, and Exporter plugins usemetadata to control their integration with the Insight webclient 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 operateswithin the Insight web client.Per-parameter metadata properties.These control the data available to plugin parameters and the organization of parameters in theInsight web client plugin options dialog.

Insight Metadata parameter groupNote: Some parameters are only available to users in the Insight/AuthorPlugins group.

Tip: For more information on any of thesemetadata parameters, select the parameter in the PipelinePilot client and review the contents of the Help panel.

Common Plugin Insight Metadata ParametersSupported Data Types

Calculator Plugin Insight Metadata ParametersRetrieve Deep PropertiesOutput Properties

Exporter Plugin Insight Metadata ParametersInput

User Selection OptionsKeep PropertiesRequired Properties

Supported Data TypesSupported Property TypesMaximumOutput Handling

Widget Plugin Insight Metadata ParametersTitle TemplateRetrieve Deep PropertiesEnable Data Connectivity

SelectionSingle Record Access

Client-Side Buffer SizeServer-Side Fetch Size

Plugin Metadata | Page 24

Additional OptionsDeveloper ModeLaunch Config WindowOutput Images

Tip: You can create aWidget, Calculator, or Exporter plugin with all the necessary metadataparameters by using the File | New Protocol from Template... option in the Pipeline Pilot client ifyou are in the Insight/PluginAuthors group.

Plugin options and parameter metadataWidget, Calculator, and Exporter plugins share a common method of exposing their protocol-levelparameters in the Insight web client. Plugin configuration is handled by the plugin options dialog inInsight.This dialog typically contains Simple and Advanced panels that expose parameters for Insight users toconfigure the plugin. These correspond to protocol-level parameters on the plugin protocol.

Simple panel showing top level parameters


Advanced panel showing the non-simple exposed parametersBy default, any protocol-level parameters on these plugins are automatically exposed in the Advancedpanel of the plugin options dialog. However, for required and other key parameters it is useful to exposethese 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 isaccomplished with the use of parameter metadata.Parameter metadata is accessible through the Edit Parameter dialog. To access this, right-click on aparameter in the Pipeline Pilot client and select Edit Parameter..., the select theMetadata tab.

Note: Parameter metadata only applies to protocol-level parameters.


Define Parameter dialog open to theMetadata tab showing possible metadata keysA parameter may have any number ofmetadata key-value pairs assigned to it and somemetadataattributes may be combined to achieve the desired result. Below is a summary of Insight pluginmetadata attributes:


Metadata key / Values Description Example

Insight_Parameter_Location

Simple Pane OnlySimple andAdvanced Pane

Explicitly promotes a parameter to a given location in theplugin options dialog.By default all protocol-level parameters appear in theAdvanced panel of the dialog.This allows you to display a parameter on the Simple paneland control whether it also remains in the Advanced panel.

Note: If all parameters are on the Simple panel, there isno Advanced panel.

Scatter Plot >Symbol Size

Insight_Expected_Type

Numeric propertyGeneric propertyField TreeFormat Picker

Determines what data type a parameter expects.For Generic Property or Numeric Property, when set to avalue, a dropdown list is displayed, autopopulated with thenames of properties in the document with the specified datatype.Field Treewill add a property tree to the plugin optionsdialog with a checkbox at every node. This will send all thechecked properties as input to the plugin protocol.Format Pickerwill provide access to conditional formattingrules on theWidget Options dialog.If no value is set the form field will default to the type of theparameter (StringType, LongType, etc...).

Scatter Plot >Data Series 1 XProperty

Scatter Plot >Symbol Color

Insight_Allow_Blank

TrueFalse

Used in conjunction with Expected Type, to render aproperty populated dropdown that can be blank.

Note: An empty value for will be interpreted as "False".

Pie Chart >ValueProperty

Insight_Allow_Constants

TrueFalse

Used in conjunction with Insight_Expected_Type, to allowconstants to be entered into dropdown lists. This allows theuser to select a property or to enter a value for the property.

Note: An empty value for will be interpreted as "False".

SimpleMathCalculator >First Operand

Insight_Auto_Label_When_Blank

TrueFalse

When true, the plugin options dialog field will have a grayedout label "<auto>" when the field is blank. This is usefulwhen you want to explain to the user that a blank valuerepresents that a default value will be created.

Scatter Plot >Data Series 1Data OptionsLegend Text


Plugin categorization and supported record typesWidget, Calculator, and Exporter plugins share a common method of declaring which category theyshould belong to and what types of data they support. Each plugin is categorized in the Insight webclient based on its location in the protocol tree.

Protocols Explorer (left) showing exporter plugin protocol pathsExporters dialog (right) for picking exporters in the web clientThe visibility of plugins in the dialog is controlled by the type of data in the current document and theSupported Data Types protocol-level parameter value. The supported options are:

GenericWill be visible and attempt to work for any dataset, but will not deserialize chemistry fromthe Insight caching system.MoleculesWill only be visible for molecular data (root node type) and will fully support chemistry.Generic and MoleculesWill always be visible and can work with generic or molecular data types.


Chapter 4:Developer ToolsThis section provides guidance to Pipeline Pilot users who are developing plugin protocols forintegration with the Insight web client.

Requirements of plugin protocolsAll plugins must:

Have protocol and parameter help - this is available as guidance in the Insight web client as a tooltipor 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 tothis 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 portEnd with anWidget Viewer componentHave an Insight Metadata parameter group at the protocol level

Calculator plugins must:Begin with an Insight Cache Reader component with an open Input portEnd with an Insight CacheWriter componentHave 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 portEnd with an appropriateWriter componentHave an Insight Metadata parameter group at the protocol level

Plugin template protocolsProtocol templates are provided to simplify the creation ofWidget, Calculator, and Exporter plugins.The templates provide all appropriate Insight Metadata settings with sensible defaults along with askeleton protocol to guide the developer. To create a protocol from template, select File | NewProtocol from Template... from themenu bar.All the Insight templates are found in the Insight folder of the template root directory.

Developer Tools | Page 30

Useful components

Insight Cache ReaderThis 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 alreadypresent in Insight. To access individual records, specify them in Filter by Records IDs parameter usingthe Record ID from a Record Inspectorwidget in the document (you may need to add this widget in theweb client to access this information).This and the other Plug-in Debugging group parameters will not have any effect on the records beingprocessed when the Insight Cache Reader receives data from an Insight web client plugin.

Insight Cache WriterThis updates the Insight cache for the document with the incoming data from previous components inthe plugin protocol.

Widget ViewerThis is used to display the output of a widget plugin in the Insight web client. When a widget pluginprotocol is run from Pipeline Pilot Professional Client, this displays the results in an HTML Report Viewer.

Convert Range to MaximumThis recognizes when a supplied Range contains a maximum value and stores this in aMaximum globalproperty so that it can later be accessed by theMaximum parameter of a reader component in a FileAdapter plugin.TheMOL SD SDF Reader default File Adapter employs this component.

File Adapter Range FilterThis filters the incoming data records according to the specified Range so that records before the lowerend of the range are removed as well as those after the upper end being excluded by theMaximumparameter on a reader in a File Adapter plugin.

Promote and Rename Deep PropertiesThis allows properties from below the top level (that is, sub-level or "deep" properties) to be promotedto the top level so that they can be accessed by subsequent components that work exclusively orprimarily with top level properties. This is a simpler strategy than trying to work with sub-levelproperties 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 promotemay be specified along with the name that the property shouldhave at the top level.However, where it is desirable that a user can choose the properties to promote a string-tokenreplacement should be used for Paths to Properties to Promote and New Top-Level Property Names.

Create Globals Containing NamesThis takes the Paths to Properties Providing Names list of deep property paths (for example,"Products/Suppliers/Company Name") and creates corresponding NewGlobal Properties Containing


Names whose values are just the names of the provided deep properties (for example, "CompanyName"). This allows property names to be preserved when they are promoted to the top level andprocessed appropriately by later components.This can be used in conjunction with Promote and Rename Deep Properties to create plugins that canhandle 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. Forexample, a Scatter Plot automatically creates axis labels and legends based on the names of theproperties being plotted. So for a chart widget that plots user specified deep properties, these need tobe promoted to the top level while preserving their names.This component stores the names of the promoted properties in known global properties defined byNewGlobal 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 NewGlobal Properties Containing Names is set to:xy

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 protocolsPlugin protocols saved with Insight 2.2 or later can be freely renamed or moved around the protocoltree (for example, into subfolders, or from development to production folders) without affecting anypreviously saved documents or templates that reference those plugins. This is because the pluginreference is based on an internal unique ID in the plugin protocol that is independent of the plugin'sname or path.

Tip: Protocols should bemoved using theMove feature in the Pipeline Pilot Client. Saving theprotocol to a different folder will create a new internal ID.

Documents and templates created with Insight 2.1 and earlier reference plugin protocols using theprotocol path. This means that if a plugin protocol is moved or renamed, some older documents maynot display all widgets when opened.Insight's deprecated protocol mapping feature provides the ability to move or rename plugin protocolswithout breaking older documents and templates. This was developed to support deprecation of somestandard plugins shipped with the early versions of Insight. When an older document or template isopened, 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 protocolpath.

IMPORTANT! Back up this file after making changes, as it will get replaced during Insight upgradesand you will need to merge your changes into the standard set of changes.


Useful Insight web client tools

Document Summary tabAll Insight documents contain a Summary tab which publishes information about document contentsand sources of data.

When the user has Insight/AuthorPlugins or Insight/PackageDeveloper roles the summary tab willreveal further internal information. For all documents it will list a Cache Idwhich corresponds to thedocument data's Mongo DB cache. For documents that were created as a result of a query the ResultsID (RSID) will be included; a variety of query service components can be used to inspect the contents ofthe corresponding result set.


Record Inspector WidgetAs long as a developer has the appropriate role, they will see the Record Inspectorwidget in the AddWidget dialog. When added to a document it allows the developer to see all properties on a given recordalong with the internal auto-generated Record Id. This record id is the unique identifier used by Insightto identify records within document data.

Error HandlingIn cases where the plugin protocol encounters an error that it cannot recover from it should use theError() PilotScript method to send a message back to the client. This message will be shown to theuser.


Chapter 5:Example Custom PluginsThis 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 theInsight/PluginAuthors group.

Building a new file adapter pluginThis example will demonstrate how to build a file adapter plugin which will allow you to read .xsd filesinto Insight (.xsd is theMaterials Studio structure format).Instructions for Advanced configuration of this custom file adapter can be used to limit the structuresread in to non-periodics only.

Requirement: You must have theMaterials Studio Collection installed to develop this example pluginprotocol.

1. Open a new protocol in the Pipeline Pilot client.2. Add aMaterial 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 theHelpwindow is "URLType".

6. Add aMaterial to Molecule converter component - this will make the output generated morecompatible with data from other sources.

7. Add a File Adapter Range Filter component and promote its Range parameter.8. In theHelpwindow 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 theWeb Applications\Insight\File Adapters\Customfolder.

Example custom plugins | Page 35

10. To test your protocol, open the Insight web client and select File in the Import Data From section ofthe Home Page. Navigate to and select aMaterials Studio XSD file, click Open.

11. The Import Previewwill show you the contents of the XSD file. Click Finish to load this into a newdocument.

Tip: You can use the Combine Data functionality to mergemultiple documents containing singlestructures.

Advanced configurationThe file types that can be read by theMaterial Reader can represent 3D and 2D periodic structures aswell as 0D discretemolecules. The simple protocol above will not handle these structures well and willdirectly report component error messages to the end user.You can enhance this protocol to provide better error reporting and filtering of unsuitable records if theinput 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 to:@structures := true;

This creates a Global Property named structures with a value of "true" to indicate that at least onerecord has passed through the Property Range Filterwith 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 to:@error := "This input file only contains periodic structures which cannotbe imported into Insight.";

This both identifies that at least one record has passed through the Property Range Filterwith aPeriodicity value different from "0D" and sets an error message to return to the Insight web clientwhen all records fail this property value check.

6. Rename this Custom Manipulator (PilotScript) to Report Error? to indicate its purpose and close itsPass port.

7. In a new pipeline add a Custom Manipulator (PilotScript) and close both its Input and Pass ports.8. Set the Expression to:

if @structures is not defined thenif @error 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 theerror message has already been set this is employed and if not a general failuremessage is created.


These error messages are returned to the Insight web client. See Error Handling for moreinformation.

9. Rename this Custom Manipulator (PilotScript) to If no structures report error to indicate itspurpose.

10. Save the protocol.

Tip: You could also add Material-specific calculator components before theMaterial to Moleculeconverter to add extra properties to the data before importing it.

Building a new data generator pluginThis example will demonstrate how to build a data generator plugin which will allow you to read create adocument containing pre-defined data.Instructions for Advanced configuration of this custom data generator can be used to provide greaterflexibility 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:

ALogPpKaMolecular FormulaMolecular WeightNum H Acceptor Donors

5. ForMolecular Formula choose to output "Molecular Composition" as well as the default.


6. In theHelpwindow for the protocol, right-click and select Edit Help Text.... Enter:Creates a document containing the 20 standard amino acids and calculatessome basic properties for them

7. Save the protocol as Amino Acid Properties Generator in theWeb Applications\Insight\DataGenerators folder.

8. To test your protocol, open the Insight web client and select Data Generator... in the Import DataFrom section of the Home Page. Select the Amino Acid Properties Generator generator.

9. The Import Previewwill show you the amino acids and their properties. Click Finish to load this intoa new document.

Advanced configurationIn order to provide greater flexibility and control over the data generated in the Insight web client youcan 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 theOutput 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 thenew 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 knowwhat they control, for example:

4. Review the parameter help for all protocol parameters, ensure that it is suitable for Insight webclient users.

5. Save the protocol in theWeb Applications\Insight\Data Generators folder, the promoted


parameters will now be available (with help as tooltips) in the Insight web client.

Building a new widget pluginThis example will demonstrate how to build a widget plugin which will allow you to add a box plot to adocument.Instructions for Advanced configuration of this custom widget can be used to automatically linkparameters to available document properties.1. Open the Pipeline Pilot Professional Client.2. Select File | New Protocol from Template... from themenu bar.3. Open the Insight folder and double-click on theWidget 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, deleteData Series 1 from the name of the promoted

parameter and click OK.8. Repeat this for the Y Property parameter, again removing theData 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.


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 webclient.

14. In theHelpwindow 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 pointsas boxes with whiskers on a chart.

15. To test your protocol, open a document in Insight. On the Summary tab, find and copy the CacheId.

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 thedocument.

17. Run the protocol.

18. When you are satisfied with the behavior of the protocol, remove the values for the Cache ID andthe X Property and Y Property protocol parameters.

19. Save the protocol in theWeb Applications\Insight\Widgets folder, the promoted parameters willnow be available (with help) in the Insight web client.

Note: In addition to the Sort Order, X Property, and Y Property protocol parameters thistemplate automatically adds the Title Template parameter to theWidget Options dialog.


Advanced configurationIn the simple initial set up of this widget, the X and Y properties are text fields and the end user mustmanually enter exactly the right name for a document property. You can perform some extraconfiguration on these protocol parameters to automatically link them to available documentproperties. You can also choose to customize the display of some protocol parameters in the Advancedsection of theWidget 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 EditParameter... from the shortcut menu.

2. Select theMetadata tab on the Edit Parameter dialog.

3. Click to add a newmetadata 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 "SimplePane 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 protocolparameters will be excluded from the Simple section of theWidget Options dialog. In this example,placing X Property and Y Property in the Simple section will force Sort Order and Title Template intothe Advanced section.

7. Save the protocol.TheWidget Options dialog now displays only the X Property and Y Property parameters in thedefault view, these are now both available as dropdown lists automatically populated with thenames of the properties in the document.


Accessing deep propertiesIn order for parameters on theWidget Options dialog to access "deep" properties (those not at the toplevel of the Properties list) and for later components to handle these, the widget plugin protocol mustbe configured to handle these properties. For more information on employing deep properties refer toAccessing 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 theNewGlobal Properties Containing Names parameter to:xy

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... fromthe 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 parametertype and setting its value to $(y).

This sets up the transfer of the properties specified in the protocol-level X Property and Y Propertyparameters to the x and y global properties and then uses these global properties in the box plotconfiguration rather than the full deep property path which cannot be processed by the Box Plotcomponent.The end user will not experience any change in the presentation of this widget after deep properties areconfigured, but the widget will be able to handle a wider range of input properties.


Building a new calculator pluginThis example will demonstrate how to build a calculator plugin which will allow you to use data in yourdocument 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 themenu 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 theOutput 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 calculableproperty in Pilot Script and you might accidentally overwrite the functionality of an existingcalculable property on the system.

8. Right-click theOutput parameter group on the protocol and select Edit Parameter....9. Select theMetadata tab, and add an Insight_Parameter_Locationmetadata key. Set the value to

"Simple and Advanced Pane". Click OK.This will display theOutput parameter on the Simple panel of the Run Calculation dialog and thegrouped parameters on the Advanced panel.

10. Select all options for theOutput parameter. This ensures that all options are checked by default inthe Insight web client.

11. Set the Supported Data Types to "Molecules" in the Insight Metadata parameter group on theprotocol as the ADMET All Models can only takemolecules as input.

12. For theOutput Properties parameter, enter the following:ADMET_Absorption_LevelADMET_BBB_LevelADMET_BBBADMET_Solubility_LevelADMET_Solubility

These are all the properties that can be generated by ADMET All Models. Enabling all properties willensure that whatever is produced is returned to the document. If any generated properties are notlisted they will never be returned to the document whether they are generated or not.

13. In theHelpwindow 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 tothe document.

14. To test your protocol, open a document in Insight. On the Summary tab, find and copy the CacheId.

15. Select the Insight Cache Reader and paste the document's Cache Id into the Cache ID parameter.


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 theWeb Applications\Insight\Calculators\Chemistry folder, the promoted

parameters will now be available (with help) in the Insight web client.


Building a new exporter pluginThis example will demonstrate how to build an exporter plugin which will allow you to generate an XMLfile containing the data from the current document.1. Open the Pipeline Pilot Professional Client.2. Select File | New Protocol from Template... from themenu 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 DataReader. Close the Input, Fail, and Pass ports and move this into an initial pipeline.

b. Set the Expression to:if @'File Name' is defined thenif @'File Name' rlike('\$\{DocumentName\}') then@'File 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 theDestination to "$(JobDir)/$(File Name)".8. Insert aMolecule 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 theMolecule to CTAB and set PropertyList to "Molecule". This will

remove the converted structure from the record to prevent duplication of the information beingstored.

10. For the protocol File Name parameter, change the "suffix" to "xml".11. In theHelpwindow 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 PluginDebugging Data URI.

Note: If you are using BIOVIA Search without an Insight license the Plugin Debugging Data URIcan 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 URIinto theData URI parameter. Run the protocol.

Building a new exporter plugin | Page 45

14. When you are satisfied with the behavior of the protocol, remove the value for theData URI.15. Save the protocol in theWeb Applications\Insight\Exporters folder, the promoted parameters will

now be available (with help) in the Insight web client.
