OmniGraffle & FileMaker: fmurlscript

Triggering FileMaker Scripts from OmniGraffle

One of the most powerful and exciting aspects of creating and implementing multi-platform FileMaker solutions, is their ability to respond to requests from other applications to execute the FileMaker script components of the targeted databases. This is accomplished by activating and using the built-in fmurlscript support in FileMaker.

To enable fmurlscript support in a database, open the file in Filemaker Pro on macOS (or Windows), and select the menu option for: File > Manage > Security… and in the forthcoming dialog, assign the privilege sets that are allowed to use this function.

The example database and scripts provided with this documentation, require full access privileges to run scrpts locally on the device.

Once enabled, you can construct URLs using the fmp:// protocol to instruct the FileMaker solution to execute one of its FileMaker scripts. You can even provide values for variables used in the FileMaker scripts!

The fmp:// protocol supports a wide range of options and parameters. You can specify network IP addresses, and even open specific FileMaker database files located the user’s Documents folder.

For the purposes of the example database included with this documentation, it is designed to reside and be hosted on the same device that has the open OmniGraffle document.

When using and targeting a local database, the fmp:// protocol provides a shortcut form for specifying the local database:

fmurlscript

fmp://$/Database%20Name?script=encoded%20FM%20Script%20Name

fmp://$/Database%20Name?script=script%20Name&$variable=encoded%20value

1 A URL for executing a FileMaker script. The dollar sign ($) indicates that the currently open database file is the target of the URL. It is followed by a forward slash and the URL encoded name of the database. The question mark (?) character delineates the parameters portion of the URL and is followed by the parameter name “script” an equals sign (=) and the URL encoded name of the script to be executed.

3 A URL for executing a FileMaker script with a specified value for a script variable. Follows the same construct as the previous URL with the addition of an ampersand character (&) followed by the name of the FileMaker script variable ($variableName) an equals sign (=) and the URL encoded value for the FileMaker variable.

Omni Automation scripts can dynamically construct fmurlscript URLs while passing information, such as the value of a graphic’s metadata tags, to the FileMaker script to be executed.

The Product Database Connector PlugIn

As an example of this technique, the “Product Database Connector” OmniGraffle PlugIn in provided for you to download and install. This plugin contains five actions (scripts) to demonstrate how to create seamless integration between an OmniGraffle document and FileMaker database.

DO THIS ►

DOWNLOAD the Product Database OmniGraffle plugin.

To install on macOS, place the unarchived plugin file in the PlugIns folder opened by selecting “Plug-Ins…” from the OmniGraffle Automation menu.

To install on iOS, tap the download link above and choose “Open” from the dialog. In the forthcoming screen, tap “More…” and then “Copy to OmniGraffle” in the popup menu.

1 The OmniGraffle Automation Menu icon (iOS).

2 The OmniGraffle Automation Menu (iOS).

3 The Product Database Connector PlugIn menu item.

4 The Product Database Connector PlugIn actions (scripts).

The Product Database Connector PlugIn actions:

> “About This PlugIn…” summons a dialog with information about the plugin.

> “Show Source Record” will switch to FileMaker and display the record whose unique identifier matches the metadata of the selected image or text container.

> “Clone with Description” will create a new text shape offset below the selected image, containing the value of the Description field of the record whose unique identifier matches the metadata of the selected image graphic.

> “Clone with Summary” will create a new text shape offset below the selected image, containing the value of the Summary field of the record whose unique identifier matches the metadata of the selected image graphic.

> “Update with Description” will replace the text of the selected shape with the value of the Description field of the record whose unique identifier matches the metadata of the selected shape.

> “Update with Summary” will replace the text of the selected shape with the value of the Summary field of the record whose unique identifier matches the metadata of the selected shape.

Show Record

The “Show Record” FileMaker script demonstrates how OmniGraffle metadata included in the fmurlscript URL can be used to display the database record whose contents are the source for the selected OmniGraffle graphic.

1 When the FileMaker script (above) is run, it first performs another FileMaker script that checks the screen orientation and adjusts the layout and window view accordingly.

2 The second action in the script will perform a simple find, searching the database records for those containing the unique identifier that was passed to the script in the URL as the value for the $TARGETID variable. Since the SKU values are unique, only the database record matching the passed SKU will be shown. All of the plugin actions targeting FileMaker use this technique.

Here is the Omni Automation action from the “Product Database Connector” PlugIn that creates and executes the fmurlscript URL to show the corresponding database record for the selected graphic.

/*{ "type": "action", "targets": ["omnigraffle"], "author": "Nyhthawk Productions", "description": "Displays the FileMaker record related to the selected graphic.", "label": "Show Related FileMaker Record", "shortLabel": "Show FM Record" }*/ var _ = function(){ var action = new PlugIn.Action(function(selection, sender) { // action code cnvs = selection.canvas graphic = selection.solids[0] DBFILENAME = graphic.userData['DB-FILE-NAME'] DBFILENAME = encodeURIComponent(DBFILENAME) DBIDFIELDNAME = graphic.userData['DB-ID-FIELD-NAME'] DBIDFIELDVALUE = graphic.userData['DB-ID-FIELD-VALUE'] FMSCRIPTNAME = 'Show Record' FMSCRIPTNAME = encodeURIComponent(FMSCRIPTNAME) urlStr = "fmp://$/" + DBFILENAME + "?script=" + FMSCRIPTNAME + "&$TARGETID=" + DBIDFIELDVALUE url = URL.fromString(urlStr) url.call(function(reply){}) }); action.validate = function(selection, sender) { // validation code if(selection.solids.length === 1){return true} else {return false} }; return action; }(); _;

Show Source Database Record

/*{

"type": "action",

"targets": ["omnigraffle"],

"author": "Nyhthawk Productions",

"description": "Displays the FileMaker record related to the selected graphic.",

"label": "Show Related FileMaker Record",

"shortLabel": "Show FM Record"

}*/

var _ = function(){

var action = new PlugIn.Action(function(selection, sender){

// action code

cnvs = selection.canvas

graphic = selection.solids[0]

DBFILENAME = graphic.userData['DB-FILE-NAME']

DBFILENAME = encodeURIComponent(DBFILENAME)

DBIDFIELDNAME = graphic.userData['DB-ID-FIELD-NAME']

DBIDFIELDVALUE = graphic.userData['DB-ID-FIELD-VALUE']

FMSCRIPTNAME = "Show Record"

FMSCRIPTNAME = encodeURIComponent(FMSCRIPTNAME)

urlStr = "fmp://$/" + DBFILENAME + "?script=" + FMSCRIPTNAME + "&$TARGETID=" + DBIDFIELDVALUE

url = URL.fromString(urlStr)

url.call(function(reply){})

});

action.validate = function(selection, sender) {

// validation code

if(selection.solids.length === 1){return true} else {return false}

};

return action;

}();

Update Description

Here’s an OmniGraffle action that updates the contents of the selected solid with the contents of the Description field of the source FileMaker record. To use, select the text container and choose the “Update with Description” menu option from the “Product Database Connector” plugin menu.

/*{ "type": "action", "targets": ["omnigraffle"], "author": "Nyhthawk Productions", "description": "Updates the contents of the selected solid with the contents of the Description field of the source FileMaker record.", "label": "Update Contents with Description", "shortLabel": "Update with Description" }*/ var _ = function(){ var action = new PlugIn.Action(function(selection, sender) { // action code cnvs = selection.canvas aShape = selection.solids[0] DBFILENAME = aShape.userData['DB-FILE-NAME'] DBFILENAME = encodeURIComponent(DBFILENAME) DBIDFIELDNAME = aShape.userData['DB-ID-FIELD-NAME'] DBIDFIELDVALUE = aShape.userData['DB-ID-FIELD-VALUE'] FMSCRIPTNAME = 'Update Description' FMSCRIPTNAME = encodeURIComponent(FMSCRIPTNAME) urlStr = "fmp://$/" + DBFILENAME + "?script=" + FMSCRIPTNAME + "&$TARGETID=" + DBIDFIELDVALUE url = URL.fromString(urlStr) url.call(function(reply){}) }); action.validate = function(selection, sender) { // validation code if(selection.solids.length === 1){return true} else {return false} }; return action; }(); _;

Update Contents of Selected Shape with Description

/*{

"type": "action",

"targets": ["omnigraffle"],

"author": "Nyhthawk Productions",

"description": "Updates the contents of the selected solid with the contents of the Description field of the source FileMaker record.",

"label": "Update Contents with Description",

"shortLabel": "Update with Description"

}*/

var _ = function(){

var action = new PlugIn.Action(function(selection, sender) {

// action code

cnvs = selection.canvas

aShape = selection.solids[0]

DBFILENAME = aShape.userData['DB-FILE-NAME']

DBFILENAME = encodeURIComponent(DBFILENAME)

DBIDFIELDNAME = aShape.userData['DB-ID-FIELD-NAME']

DBIDFIELDVALUE = aShape.userData['DB-ID-FIELD-VALUE']

FMSCRIPTNAME = 'Update Description'

FMSCRIPTNAME = encodeURIComponent(FMSCRIPTNAME)

urlStr = "fmp://$/" + DBFILENAME + "?script=" + FMSCRIPTNAME + "&$TARGETID=" + DBIDFIELDVALUE

url = URL.fromString(urlStr)

url.call(function(reply){})

});

action.validate = function(selection, sender) {

// validation code

if(selection.solids.length === 1){return true} else {return false}

};

return action;

}();

Update Summary

Here’s an OmniGraffle action that updates the contents of the selected solid with the contents of the Summary field of the source FileMaker record. To use, select the text container and choose the “Update with Summary” menu option from the “Product Database Connector” plugin menu.

/*{ "type": "action", "targets": ["omnigraffle"], "author": "Nyhthawk Productions", "description": "Updates the contents of the selected solid with the contents of the Summary field of the source FileMaker record.", "label": "Update Contents with Summary", "shortLabel": "Update with Summary" }*/ var _ = function(){ var action = new PlugIn.Action(function(selection, sender) { // action code cnvs = selection.canvas aShape = selection.solids[0] DBFILENAME = aShape.userData['DB-FILE-NAME'] DBFILENAME = encodeURIComponent(DBFILENAME) DBIDFIELDNAME = aShape.userData['DB-ID-FIELD-NAME'] DBIDFIELDVALUE = aShape.userData['DB-ID-FIELD-VALUE'] FMSCRIPTNAME = 'Update Summary' FMSCRIPTNAME = encodeURIComponent(FMSCRIPTNAME) urlStr = "fmp://$/" + DBFILENAME + "?script=" + FMSCRIPTNAME + "&$TARGETID=" + DBIDFIELDVALUE url = URL.fromString(urlStr) url.call(function(reply){}) }); action.validate = function(selection, sender) { // validation code if(selection.solids.length === 1){return true} else {return false} }; return action; }(); _;

Update Contents of Selected Shape with Summary

/*{

"type": "action",

"targets": ["omnigraffle"],

"author": "Nyhthawk Productions",

"description": "Updates the contents of the selected solid with the contents of the Summary field of the source FileMaker record.",

"label": "Update Contents with Summary",

"shortLabel": "Update with Summary"

}*/

var _ = function(){

var action = new PlugIn.Action(function(selection, sender) {

// action code

cnvs = selection.canvas

aShape = selection.solids[0]

DBFILENAME = aShape.userData['DB-FILE-NAME']

DBFILENAME = encodeURIComponent(DBFILENAME)

DBIDFIELDNAME = aShape.userData['DB-ID-FIELD-NAME']

DBIDFIELDVALUE = aShape.userData['DB-ID-FIELD-VALUE']

FMSCRIPTNAME = 'Update Summary'

FMSCRIPTNAME = encodeURIComponent(FMSCRIPTNAME)

urlStr = "fmp://$/" + DBFILENAME + "?script=" + FMSCRIPTNAME + "&$TARGETID=" + DBIDFIELDVALUE

url = URL.fromString(urlStr)

url.call(function(reply){})

});

action.validate = function(selection, sender) {

// validation code

if(selection.solids.length === 1){return true} else {return false}

};

return action;

}();

UNDER CONSTRUCTION

This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.

DISCLAIMER

Mention of third-party websites and products is for informational purposes only and constitutes neither an endorsement nor a recommendation. OMNI-AUTOMATION.COM assumes no responsibility with regard to the selection, performance or use of information or products found at third-party websites. OMNI-AUTOMATION.COM provides this only as a convenience to our users. OMNI-AUTOMATION.COM has not tested the information found on these sites and makes no representations regarding its accuracy or reliability. There are risks inherent in the use of any information or products found on the Internet, and OMNI-AUTOMATION.COM assumes no responsibility in this regard. Please understand that a third-party site is independent from OMNI-AUTOMATION.COM and that OMNI-AUTOMATION.COM has no control over the content on that website. Please contact the vendor for additional information.