You can use the MDriven Turnkey Excel Plugin to read the first grid from a MDriven Turnkey application into Excel, seek Turnkey data from an Excel selection, and write selected Excel values to a compatible Seeker; this page is for users of the legacy Excel AddIn workflow.
The excelImport function is deprecated. For the generic, current approach to ViewModels, import, export, multi-search, synchronization, and Excel, use Documentation:Convergence â ViewModels, import, export, multi search, synchronization and Excel.
Before you start
Install the add-in by following HowTos:Install Turnkey Excel Plugin. The plugin runs inside Excel and displays your Turnkey application in an embedded browser.
You need:
- Microsoft Excel with the MDriven Turnkey Excel Plugin installed.
- The URL of the MDriven Turnkey application that you want to use.
- Access to the relevant Turnkey UI.
- A ViewModel designed for the operation you want to perform.
The plugin uses the data and UI that Turnkey exposes to the signed-in user. It does not expose arbitrary database tables or bypass the access groups and view design in your application.
Open a Turnkey application in Excel
- In Excel, open the AddOns tab.
- Start the MDriven Turnkey Excel Plugin.
- In the plugin window, paste the URL of your MDriven Turnkey application into the box at the top.
- Select Go.
- Navigate in the embedded browser to the Turnkey view that you want to use.
The plugin window contains the Turnkey application. The active Turnkey UI determines which data the plugin can download, seek, or update.
Download grid data to Excel
You can copy the data from a Turnkey grid into the worksheet.
- In the embedded Turnkey application, open a view that contains a grid and make the data you need visible.
- In Excel, select the cell where the downloaded data should begin.
- In the plugin, select Download to Excel.
The plugin downloads the data shown in the first grid in the Turnkey UI and places it starting at the selected Excel cell.
For example, if the first grid displays Person rows with the columns Identity, Name, Company, and Country, selecting cell A1 before downloading places that grid starting at A1.
Gotcha: only the first grid in the displayed Turnkey UI is used. If the view contains more than one grid, arrange the view so that the grid you want to download is first.
Seek Turnkey data from selected Excel cells
You can use values selected in Excel to build up results in a Turnkey Seeker. A Seeker is a Turnkey UI that searches for objects and displays matching objects in its result grid.
- In the embedded browser, open the target Seeker UI.
- In Excel, select the cells whose values you want to find.
- In the plugin, select Seek Selected in Turnkey.
The plugin seeks each selected cell value in the Seeker. Matching objects accumulate in the Seeker result grid.
For example, select four identity values in Excel and run Seek Selected in Turnkey. The Seeker searches for those identities and adds the matching Person objects to its result grid.
Write selected Excel data to Turnkey
You can update existing objects, and potentially create missing objects, by writing a rectangular Excel selection to a compatible Turnkey Seeker.
Prepare the ViewModel
Configure the Seeker result grid in MDriven Designer before using the write operation.
| Requirement | Why it matters | Example |
|---|---|---|
| The active Turnkey UI is a Seeker. | The plugin uses the Seeker to locate objects and display the result. | A Person Seeker displays Person objects in its result grid. |
| The key is in the leftmost grid column. | The plugin uses the first selected Excel column to find an existing matching object. | Put Identity before Name, Company, and Country.
|
| Columns that Excel may change are writable in the ViewModel. | Read-only columns are not targets for updates. | Make Name, Company, and Country writable when users should edit them from Excel.
|
A ViewModel action named CreateNew exists when missing objects may be created.
|
The plugin looks for this exact action name if it cannot find an object by key. | A Person Seeker has a CreateNew action that creates a Person object.
|
A CreateNew action must create an object of the same class as the objects in the Seeker result list. When the plugin creates a new object, it assigns the first-column key and then assigns values to the other writable columns.
For example, a Person grid can use this column order:
| Excel column | Seeker grid column | Use during write |
|---|---|---|
| A | Identity | Finds the existing Person. For a new Person, supplies its identity. |
| B | Name | Updates the writable name value. |
| C | Company | Updates the writable company value. |
| D | Country | Updates the writable country value. |
For a single-valued association, design the corresponding grid column as a ComboBox. The plugin can use this preferred lookup assignment mechanism for single links.
Write the Excel selection
- In the embedded browser, open the prepared Seeker.
- In Excel, select a rectangular area that includes the key in its leftmost column and the values to write in the remaining columns.
- In the plugin, select Write Selected to Turnkey.
- Review the changes in Turnkey.
- Use Turnkey's Save to persist the changes, or Cancel to discard them.
For each selected row, the plugin uses the leftmost value to seek an existing object. If it finds one, it assigns values from the remaining selected columns to writable grid columns. If it does not find one and a CreateNew action is available, it creates an object, gives it the key, and assigns the remaining writable values.
After the plugin changes data, Turnkey shows its Save/Cancel option. The Excel selection is therefore not committed until you save in Turnkey.
Important behavior: for an existing object, the key column is used to find the object; it is not updated. For a newly created object, the key is assigned when the object is created.
Design and security considerations
Keep the Excel grid aligned with the Seeker grid. In particular, make the Excel columns match the intended grid-column order, with the key first. Test writing with a small selection before loading a larger worksheet.
The plugin works through your Turnkey application rather than directly against the database. Users can work only with data that the ViewModel exposes and that their authorized Turnkey access permits. Design the ViewModel and access groups accordingly.
When to use another export mechanism
This plugin is for exchanging data with a running Turnkey application. It is not the mechanism for exporting information about the MDriven model itself. To export data from MDriven Designer or Modlr extensions, see Documentation:MDriven Designer and Modlr extensionsâexporting data. For plugin development in the design environment, see Documentation:Modlr plugin and Documentation:Plugins in Modlr.