::: tip Prerequisites
To follow along with this tutorial, you will need to register with Speckle. It takes less than 1 minute!
:::
Installation
Unlike other connectors, the Speckle Connector for Excel is distributed via the Microsoft AppSource store.
To install it:
- Open Excel (for Desktop or Web)
- Click on Insert > Office Add-Ins
- Search for
speckleand click Add
::: tip
You can also install it straight away from the Microsoft AppSource Store.
:::
After installing the connector, it should appear in Excel under the Home ribbon like so:
Logging In
You'll need to log in to use this connector as it is unable to access your accounts from Speckle Manager. To do so, simply type your server url click on the log in button and insert your credentials.
::: tip IMPORTANT 🙌
Currently, only accounts on servers managed by us are supported, this is because of limitations on the Microsoft Office Store. To use the Excel connector with a server deployed by you, you'll have to publish it yourself.
:::
Adding Streams
Just click the top left menu > Add stream > click on a stream to add to the document. The stream will be saved in the document and available whenever you return to it.
By default, streams are added as receivers but you can easily switch them to sender mode.
Receiving Data
Receiving data in excel is quite different than in other connectors, and this is because we need to "flatten" it so to represent it in a table format. In general, a stream will either contain:
- Simple values like numbers, text etc
- Complex data structures (objects) like a Revit Wall or a Grasshopper Line. Objects are identified by a
{}symbol.
The Excel connector works best when receiving lists of either simple values or objects of the same type. Lists are identified by a [] symbol.
Since a commit can contain a variety of data types, after clicking the receive button, you'll have the possibility to expand and select which data inside it to actually pull and write to your Excel file. You don't have to receive an entire commit each time!
Simple Values
When receiving lists (or lists of lists AKA tables) of numbers or text, the data is received without transformations and the values are outputted by default in rows. Therefore, a single list will write data to a single row, a list of lists to multiple rows. If the incoming data has any further levels of nesting, it will be "string-ified".
Objects
When receiving lists of objects they are flattened. This means that each object will become a new row and all its property values (and sub-property values) will become columns, their names will be the headers. Individual objects can be received too, and only one row will be created.
::: tip Tip 🙌
We recommend receiving lists of objects that have the same underlying data structure, i.e. only receiving objects of the same type.
:::
Nested objects are flattened as well and their properties delimited by a period .. See the example below where 10 lines have been streamed from Dynamo to Excel:
Complex Objects
When receiving complex objects (with more than 25 properties or sub-objects), you'll be presented with an additional dialog. This will let you filter which columns are to be received.
Sending Data
Similarly to receiving, data can be sent a list of simple values or of objects.
Simple values
Just select the range of data you want to send and click "Set range"
This is how it'll look in Speckle.
Objects
To send objects, just replicate the structure of objects that you have previously received, then select "Set range with headers".
For instance, you could create 10 new lines with the data below:
Conclusion
We hope you enjoyed this tutorial and found it useful!
Speckle is an Open Source project and we really ❤️ feedback, so if you have any questions, comments, critiques, or praises please let us know on our community forum.
