Introduction

This document provides a list of all supported actions along with their parameters, result format and when they are called by Measure.

It is good to know one key thing. Actions 0 and 1 below have been available since at least Measure 3.0 and are compatible with nearly any edition of Measure. Actions 100+ were added more recently and are supported by Measure 2010 and newer. The original actions 0 and 1 are still supported and work fine if they meet your needs.

The newer methods have the advantage of supporting the concept of “linking”. Product and customer information captured using these new methods can be refreshed by the user so that Measure stays up to date with price changes, etc.

NOTE: Be sure to return an empty string or "false" in response to any SupportsAction() calls you do not recognize. Otherwise, as new actions are created in the future your plug-in may behave unexpectedly.

List of Actions

Action ID	Name	Description
0	ImportProducts	Requests the plug-in to display its own product selection dialog (see also 101)
1	ExportWorksheet	Exports product information (in either a simplified format or a new enhanced version – see action 109)
5	NHMS	Special export of product selections to NHMS
100	IsProductDB	Return true if you intend to use product linking.
101	SearchProductDB	Measure user is searching for a product. Search parameters are passed in, results are returned by the plug-in.
102	CloseProductDB	Measure is closing. This message is sent as a courtesy to the plug-in in case it needs to release resources.
104	GetProduct	Measure is requesting more detailed information (including colors and prices) about a specific product.
105	ConnectToDatabase	Measure is asking the plug-in to try and connect to its data source to verify that everything is working.
106	GetSaleTypes	(Optional) Measure is asking for a list of "sale types".
107	GetKeyValueList	(Optional) Measure is asking for a list of key/value pairs. This is optional, but if supported allows the plug-in to provide new captions for some controls.
108	SearchCustomers	Measure user is searching the customer list.
109	ExtendedExportData	Measure user is exporting the order to the plug-in. The structure of the XML is the same as that used when choosing Export to XML in Measure.

Action 0 – ImportProducts

When Called

If your plug-in returns true when asked SupportsAction(0), it will be listed in the Import from... list in both the Products dialog and the Project Information dialog. When a user selects your plug-in from the list it will be called with the appropriate parameters.

Parameters

When called from the Products dialog you will receive a node like this:

Title will be the word “Import” followed by the text of the currently selected tab in the Products dialog. You may optionally use this attribute as the title for your dialog box.

Subtype will be a valid Measure product subtype. See appendix A. Your plug-in will be expected to return products that match this type of product.

When called from the Project Information dialog you will receive this node:

Return Value (for Products)

Your plug-in should present its own user interface to help the user find the information in your database and then return a string in the following format (carriage returns optional, but included for clarity):

Each Product node should conform to the Product XML Specification (see Appendix B).

Return Value (for Customers)

You should return one <Customer> node as an XML string (see Appendix C).

Notes

If your plug-in returns true for IsProductDB this action (ImportProducts) will never be called. Instead, your plug-in will be expected to implement SearchProductDB and SearchCustomers instead.

Action 1 – ExportWorksheet

When Called

If your plug-in returns true when asked SupportsAction(1), it will be listed in the Export to... list on the Worksheet. When a user selects your plug-in from the list it will be called.

Parameters

The parameter is this action is the export data in XML format. Documentation for this format can be found here:

XSD:
http://www.measure411.com/schema/MeasureExport/MeasureExport.xsd

XSD diagrams and notes:
http://www.measure411.com/schema/MeasureExport/doc/#Link069A9420

Help getting started:
http://www.measure411.com/schema/MeasureExport/doc/MeasureExport.pdf

Return Value

Optionally, may return a <result> node in this form:

<result success='true'>message</result>

The success attribute may return false to tell Measure that the export failed. The content of the element may be used to pass a message about the transaction, why it failed for example. For backward compatibility, a blank return value (or any other return value) is considered “successful”.

Note that Measure currently ignores the return value, as it always has. This was added to support the new Measure Cloud Importer utility which uses the return value to decide whether or not to mark the job as imported.

Notes

There is a trick to this action. ExportWorksheet can actually return two versions of the XML format. An old, simplified one and the current detailed one. We do not recommend that you try to work with the old version which only exists to support legacy plug-ins. To get the correct version of the worksheet data your plug-in can do one of two things:

Return true to SupportsAction(109), that is: ExtendedExportData (recommended)

Include the text “[V3]” in the display name of your plug-in. Not recommended, but explains why you may sometimes see this text in the name of a plug-in.

Action 5 – NHMS

When Called

When the user selects Export take-offs to NHMS (RFMS Link), the first plug-in installed which returns true when asked SupportsFeature(5) will be used.

Parameters

You will be sent one Rooms element with a child Room element for each room in the project. Each of those in turn have an Estimate line for each product defined in the product file selected for the export:

See the document NHMS Integration Specification for a detailed description of this data.

Return Value

Igoned

Notes

This is part of a special multi-step process for NHMS. See the document NHMS Integration Overview for more information.

Action 100 – IsProductDB

When Called

Measure calls this method when the plug-in is loaded to determine whether or not this plug-in should be treated as a “database plug-in”; that is, a plug-in that supports the extended actions 101-108 and that use the Measure interface to search for data and supports linking.

Parameters

This action is never called with PerformAction() by Measure. Instead, your plug-in should simply return true to SupportsAction(100) if you will support this behavior.

Notes

There can only be one Database plug-in active at any time in Measure. If more than one database plug-in is registered with Measure the first one in the plug-in list will be the active one. You can see which is active by checking the Database tab of the Options dialog.

As you will see in the following pages, plug-ins that use this method will not appear in the drop-down lists on Products and Customers but instead will integrate into the Measure user interface directly.

Action 101 – SearchProductDB

When Called

If your plug-in returns true for SupportsAction(100) then a Find tab will be available on their Select Product dialog box. The user may select a product type and enter some text in the Find box. When they click the Find button, that’s when your plug-in will be called.

Your plug-in will return product level results (the left pane). Then, if they click on a specific product details will be loaded into the right pane by a subsequent call to GetProduct (action 104).

Parameters

Your plug-in will be passed a node like this:

<Command name='SearchDB'><SearchText>GOLD</SearchText><ProductFilter>RollCarpet</ProductFilter></Command>

SearchText will be text they entered in the box. ProductFilter will be a product subtype (see Appendix A) corresponding with the value they chose from the drop-down list.

Return Value

A <Products> node with zero or more products matching the search criteria. See Appendix B for all the fields that may be provided. However, it is anticipated that your code will not return child nodes for colors and prices. This will make the search process faster since much less data will need to be parsed. When those child nodes are missing, the Select Product dialog will make subsequent calls to GetProduct (action 104) to get the color names and available prices.

At a minimum you would return the following elements:

<StyleName>GOLD COAST</StyleName>

</Product>

</Products>

Note

Take note of a special attribute here not normally found in the Product specification: the masterid. This little attribute tells Measure that this ID may be used on a subsequent call to get more information about this product or to later get fresh information for the product from the database. It is expected that masterid and id will be the same.

Action 102 – CloseProductDB

When Called

If your plug-in returns true for SupportsAction(100), Measure will call this action when the application is shutting down if Measure communicated with your plug-in during the Measure session.

Parameters

None.

Return Value

None.

Action 104 – GetProduct

When Called

This method may be called at various times.

When using the Search product dialog (see the description under Action 101 – SearchProductDB). When one of the main products are clicked, this method will be called to fetch the colors and prices.

Once a product has been selected using this process, it is “linked”. It appears in the Measure product list with a little link icon and some additional buttons will appear at the top:

These buttons are Refresh, Link, Unlink and Re-price.

When Refresh is clicked then any linked products are checked using GetProduct for updates to key data attributes (description, price, etc.)
When Link is clicked, Measure will attempt to “link” a normal Measure product with the database by looking it up by ID using the GetProduct call.

Parameters

Your plug-in will receive:

The product ID to get.

Return value

This should return a complete <Product> element as defined in Appendix B. Note that unlike the return value for SearchProductDB there is no parent <Products> node since only one Product is being returned. Here is an example of a minimum number of elements being returned:

<StyleName>GOLD COAST</StyleName>

<ColorName>ALDEN CHARCOAL</ColorName>

</Color>

<ColorName>AQUITANE</ColorName>

</Color>

</Colors>

</Prices>

</Product>

Action 105 – ConnectToDatabase

When Called

Measure calls this method before calling any other database-related data request (101, 104, etc.) It provides your plug-in with an opportunity to cleanly halt the process if for some reason your data source is unavailable. For example, if before using your plug-in the user must perform some kind of configuration (specify connection information, etc.) this method would be a good place to check and make sure all is in order.

This method is optional. You can simply return an empty string.

Parameters

Your plug-in will receive an empty string. There are no parameters.

Return value

If your plug-in returns the string “False”, this will be interpreted as a failure to connect and the following message will be shown to the user:

Your product database plug-in has not been configured correctly.

Any other return value, including an empty string, will be interpreted as success.

Action 106 – GetSaleTypes

When Called

A sale type is really a price level. This method is called whenever a master list of sale types (price levels) needs to be generated. Products may optionally include multiples prices. Each price is associated with a sale type. Not all products will supply a price for all sales types and sometimes the system needs to know all the possible sale types that might come up. There are currently three such situations.

On the Options dialog, under the Database tab the user may choose the default price level to bring in when linking products. When the user clicks Change the GetSaleTypes method is called to populate the drop-down:

Also, on the Products dialog when either the Reprice or Link button is clicked, a dialog is presented to request the price level to use. GetSaleTypes is used to populate the drop-down.

Parameters

None. Measure will just send an empty string.

Return value

The plug-in should return data like that shown below:

</SaleTypes>

Only DataKey is actually used by Measure today, although originally the thought was that a descriptive name could also be included. This still may be supported in the future but if present is ignored and can be omitted.

The DataKey associated with prices for products (see Appendix B) is expected to match one of the DataKey values returned by this method.

Action 107 – GetKeyValueList

When Called

This method was added to support a variety of choose lists added to Measure that could be populated by an outside source. Rather than create a series of method calls, this single method accepts a "list id" parameter which tells the plug-in which set of key/value pairs is desired.

In Measure today, this method is called to support four drop-down lists on the Project Information dialog: Job Type, Salesperson, Second Salesperson and Store. The method is called when the drop down is first opened, rather than when the dialog is opened.

Parameters

LIST_ID should be one of these values: SalesPerson, JobType or Store

Return value

The plug-in should return data like that shown below:

<Item DataKey="2">HOUSE</Item>

<Item DataKey="3">STEVE</Item>

<Item DataKey="4">SUSAN</Item>

</KeyValueList>

Regardless of the LIST_ID requested, the same basic XML structure is returned. The DataKey and values should correspond with the requested list. The DataKey selected should be a unique identifier that has meaning to your system.

Action 108 – SearchCustomers

When Called

The Project Information dialog has a button to link to a database customer.

When clicked, the Find Customer dialog appears. SearchCustomers is called when the Find button is clicked.

This method is also called when the Refresh button is clicked on the Project Information dialog to get updated customer data from the database. Unlike products which have two methods for getting data, a search and a get – customers have this one method which supports both behaviors.

Parameters

<CustomerNumber>CUSTOMER_ID</CustomerNumber>

<ProjectNumber>PROJECT_ID</ProjectNumber>

</Command>

If performing a product search, the text the user entered will be supplied in the SearchText element. If fresh information is desired about an already linked customer/project, the linked CUSTOMER_ID and PROJECT_ID will be supplied.

The CustomerNumber will be the value originally returned by the plug-in for the Customer/LinkedCustomerID element, likewise the ProjectNumber should be the value given for LinkedJobID.

Return value

In either usage, the results should be returned in the structure below with a single Customers root with one or more Customer records within.

</Customers>

The individual Customer elements should match the format described in Appendix C.

Action 109 – ExtendedExportData

When Called

Measure calls this method when you call Action 1 (ExportWorksheet) to determine whether or not to send the complete export format or the old legacy simplified version.

Parameters

This action is never called with PerformAction() by Measure. Instead, your plug-in should simply return true to SupportsAction(109) in order to receive the correct version of the worksheet XML.

Appendix A: Valid Product Subtypes

RollCarpet

RollVinyl

RollWallpaper

RollSlab

TileOther

TileCeramic

TileWood

TileLaminate

ItemMisc

ItemService

PlankWood

PlankLaminate

CeilingTile

These correspond with the tabs on the Product dialog:

Appendix B: Product XML

Schema Notes Required

<Product

id="", Unique numeric identifier for the product ü

rgb="", HTML style color code to use

masterid="", Should be same as id – used to tell Measure this is a ü

"linked product"

code="", A valid product subtype (see Appendix A) ü

xef="", External code (usually RFMS PC code)

addOnOnly=""> True if this product can only be used as an add-on

<StyleName /> Name of the product ü

<LabelWidth /> Width used for selling

<EstimateWidth /> Width used for estimating – usually the same, but might

be less if there is selvedge

<PatternWidth /> Width of pattern (or tile)

<PatternHeight /> Height of pattern (or tile)

<PatternDepth /> Depth of tile (used to figure grout)

<PatternDrop /> Drop repeat. Valid values: 0.5 (1/2), 0.333334 (1/3), 0.25 (1/4), 0.125 (1/8).

<ExtraWaste /> Additional waste to always include with this product

<ExtraWasteIsUnits /> Usually ExtraWaste is assumed to be a percentage. If this

value is True, it will be treated as a number of units

<MaxTseams /> Maximum number of T-seams permitted (for roll products)

<CutGap /> Cut gap (for roll products) or default grout width (for tile)

<SquareCut /> Use "square cuts" feature for allocating rolls

<SaleUnits /> Sale units. Valid values are: SF, SY, SM, LF, YD, LM, EA, ü

HR, CI, CMM

<BoxCount /> Box count

<PricePerUnit DataKey="" /> Price used in estimates for this product. Only one price is

active at a time in Measure, although the Prices element

may define additional choices.

<Freight /> Freight cost of product (per unit)

<CostPerUnit /> Cost of the product. This is actually not used in Measure

currently, but if provided is included in the export data.

<Taxable /> True if subject to sales tax.

<Color id="" rgb="">color name</Color> Each color is listed. Note that color ID's need only be unique

within this product.

</Colors>

<Prices> This optional element is only supported for the GetProduct

<Price DataKey="" Label=""></Price> action (104) and is ignored at other times. It allows your plug-in

</Prices> to provide additional prices from which the user may choose.

</Product>

Appendix C: Customer XML

<City>

<State>

<Phone>

<Email>

<Occupied>False</Occupied>

<Zone/>

<Map/>

<Lot/>

</PropertyDetails>

</Customer>

Introduction

List of Actions

Action 0 – ImportProducts

When Called

Parameters

Return Value (for Products)

Return Value (for Customers)

Notes

Action 1 – ExportWorksheet

When Called

Parameters

Return Value

Notes

Action 5 – NHMS

When Called

Parameters

Return Value

Notes

Action 100 – IsProductDB

When Called

Parameters

Notes

Action 101 – SearchProductDB

When Called

Parameters

Return Value

Note

Action 102 – CloseProductDB

When Called

Parameters

Return Value

Action 104 – GetProduct

When Called

Parameters

Return value

Action 105 – ConnectToDatabase

When Called

Parameters

Return value

Action 106 – GetSaleTypes

When Called

Parameters

Return value

Action 107 – GetKeyValueList

When Called

Parameters

Return value

Action 108 – SearchCustomers

When Called

Parameters

Return value

Action 109 – ExtendedExportData

When Called

Parameters

Appendix A: Valid Product Subtypes

Appendix B: Product XML

Appendix C: Customer XML

Comments