GraphQL API | Create Speckle Document Management App

Help
1

Hey,
I want to link my Document Management Tool (for example Google Docs or Sharepoint) with my custom Speckle Viewer in my own Speckle App.

The idea behind is that I want to give other stakeholders who do not use Revit the option, to link documents to my e.g. Rooms or Walls. So in the end I can link all relevant document for that room to that room in the 3D viewer in the web.

I know that I could use the speckle comments for that but I want to provide a nice overview of the documents and do not want to click through all the comments attached to an object.

So my idea is to create Base Objects which represent “Parameters”. Each time the user adds a Link to a document through the front-end to an e.g. wall, I create a Parameter Object for it, link it to that wall object and commit to the stream.

Can I create Base Objects with the GraphQL API and make a new commit through
GraphQL to the stream? If yes how do I make sure my JSON which I send in the end has the right format for a base object?

It that how Speckle wants me to do it or is there a better way. I want to do it through the front-end since I use serverless functions on netlify which do not provide a python backend.

My other idea was to use the speckle comments and save a JSON dict into them. Then I just query them for my JSON objects. But I guess that is not the intended way of how to use the comments. Or should I just do it this way?

2 Likes
2

In general, there shouldn’t be obstacles to any of what you are suggesting, but I have a few follow-up questions before launching a string of possible options at you.

On the assumption that you are wrapping the Speckle viewer in your App frontend to your own server, my personal preference would be that your App GraphQl queries the stream Comments and parses it out to display itself as a list of Docs/Links.

The option to create objects on each Comment with an attachment and then have a mechanism to in-turn parse those objects for display/interaction seems a complicated architecture.

However, that is making a lot of assumptions of your project. As there are a few different ideas in your question that I’d like to group into “themes.”

Document Support in Comments

  • In your described scenario, are we still talking about stakeholders attaching documents to comments attached to objects?
  • Google Docs and Sharepoint are likely to URIs rather than binary files but the outcome is similar.

This is currently the most supported method of contextually storing binary content in the :speckle: Speckle server. Particularly with existing frontend behaviours to suit.

Your SpeckleApp

  • Does this present itself with a FrontEnd to the stakeholders?
  • Is this where the list of Object/Comment/Documents are displayed to stakeholders?
  • Would it show a list of the Documents and associated links to objects in the server/viewer?
  • Or is it simply the headless entity that runs your functions?

Your Parameter Objects

  • how is that object linking managed?
  • what do you expect/intend UX to be?
  • Will the Parameters Objects be discrete for the per room/wall?
  • Or per stream but grouped by element?

Artisinal Base objects (via JS)

You actually have two options for creating objects with native JS. You can post a GraphQL Mutation as you’ve alluded to, or you can commit objects directly with the REST API.
There is no real advantage to either other than familiarity and perhaps documentation. However, the important thing to note is that neither route will decompose, serialize or chunk your objects for you.

Depending on your answers, lots of things might be possible.

1 Like
3

Hi Jonathon,
thanks for your response.

To describe it as simple as possible we try to solve the following problem here:
Our clients often have certain requirements e.g. they want a certain Wallpaper in a room. Whenever this happens we note down theses requirements in Notion or in a long excel list room by room.

So instead of having these information somewhere in an excel, we would like to link them to our BIM Model.
What we thought of was at first that we just add the requirements as links (URLs) inside revit to the concerning objects (with Parameters). However, Revit is just not built for that (UX) and everybody who wants to access these information needs a revit license.

So the idea instead is to built a custom web app with speckle, where we make use of the Speckles Javascript Viewer in combination with a simple UI which takes away all of the complexity. It should be simple.

When we have a meeting with a client we want to use that app and click through the different e.g. rooms.

When I click on an object (e.g. room) I have the option to link documents to it through URLs. We could here for example implement the google document picker. In addition, I see an overview of all the documents already linked.

The main goal is that the client can click through the e.g. rooms herself and attach relevant documents (URLs) easily. So in the end every specialist (e.g. fire expert) can attach the relevant documents to the different BIM objects to be able to access them all in one place.

We basically want that all our data is linked to the BIM Model through an easily accessible UI for every stakeholder. So the underlying question is should I use the speckle comments for that? Are they part of the BIM model or better is that their intended use?

I mean there is even more to it. Right now we are just experimenting with speckle because it is amazing. But it is missing the simple user interfaces which enable designers or domain experts to interact with it though simple workflows. I have the feeling that speckle wants people like us to build those tools on their own by providing such excellent support and documentation. Or is speckle going to build soon simple tools like this on their own soon?

So here are the answers to your questions:

  1. Yes we talk about stakeholders attaching URLs of documents which are stored in our document management system (Google Drive)
  2. Yes we do not want to build another Document Management Tool we just want to link URLs form Google Drive
  3. Yes it does. With a LogIn through their Speckle Account
  4. Yes its a React Front-End with the Javascript Speckle Viewer making use of the GraphGL API
  5. Yes
  6. No
    Your Parameter Object:
  7. We do not know yet. Speckles Comment feature seem simple enough but are they part of the BIM Model? This is more a generell question. Should I save above described information into the comments or the Object Three of Speckle
  8. I hope I described it above clearly.
  9. / 10. I guess I have to work myself more into the Speckle Concept…

Artisanal Base Object
When I upload a batch of Object via the RestAPI does this create automatically a commit?

1 Like
4

That’s all a lot clearer.

I’ll digest that a little and get back to you. In the meantime:

[Speckle] is missing the simple user interfaces which enable designers or domain experts to interact with it through simple workflows.

Interaction with Speckle is read-only on the server and read-write using Connectors or SDKs. We actively support workflows around those two key scenarios and are always keen to hear how this could be improved.

Are [comments] part of the BIM model or better is that their intended use?

That is why comments are only part of the “BIM Model” in the loosest sense. If the Speckle server represents the BIM Model, they are part of that… but not strictly part of the BIM model in the way that they are separated from your committed objects - they are Stream metadata. This would become apparent if any new version of a room/wall uploaded to Speckle would not be attached to the previous comments. This is a limitation we are looking at (complex with multiple software and different understandings of element IDs)

I have the feeling that speckle wants people like us to build those tools on their own by providing such excellent support and documentation. Or is speckle going to build soon simple tools like this on their own soon?

The Speckle server and its frontend is not intended to have all features to all comers; this is true. It is intended to be a stable set of core functionality. It will increase the features around some core ideas. But it isn’t intended to include “authoring” tools. We have ideas about how the core could be extended by you or us (frontend and backend | plugins/functions etc.), but nothing concrete on that just yet. We are encouraging you to “bring your own code” and will support you wherever possible.

1 Like
5

Hi!

Just wanna throw an idea here.

Your web app can be a connector, that author objects using pure the GraphQL/REST API to a different branch. Your objects could look sort of like this:

{
    "doc_refs": ["wallpapers.com/amazing.jpg", "wallpapers.com/classic.jpg"],
    "object_ref": {
        "speckle_stream_id": "632fbe3973",
        "application_id": "a-room-guid-provided-by-revit-thats-unlikely-to-change"
    } 
}

While you keep commiting using the connectors to the “main” branch, your webapp commits to another branch, where you manage these documents. Now, the way to hook things is by looking for the applicationId of your rooms, which is provided by Revit, since the speckle object id could change from commit to commit.

image
image1212Ă—817 87.6 KB

Someone please correct me if I’m wrong :sneezing_face:. (1) will change if a property of that room change, and the room is commited. (2) will change only if it’s really a new revit room.

Finally, when it comes to meeting the client. You need to “merge” the two things basically fetching your objects on the viewer, fetching your document references from the docs branch and writing the code to hook things together.

1 Like
6

Exactly - so the only “gotcha” is you remove that room altogether, as long as the applicationId stays the same.

That would indeed work - basically overlay the “meeting notes” data with essentially the BIM model.

Nevertheless, to @VinzenzTrimborn’s question around comments: they definitively can work as well, possibly even a bit more out of the box. You can currently literally just drag and drop files into the comment field to attach them in a thread. There are a few limitations currently that will be removed:

  • comments are currently attached only to a commit (soon to be renamed to version) - in the future they will be attached to a branch (soon to be renamed to model). This way you can track them across version (sic) changes.
  • we, if i recall correctly, out of pure laziness (yep, double checked, i even left a comment to that effect[0]) do not store the selected objects inside the comment. this can though be easily done.

Implementing all the comment magic though is a tall order for a new application, so it might be more feasible to go the “overlay” mode that @vwb suggested.

To further detail @jonathon’s answer here - it’s a both yes and no:

We will never be able to capture all ends of workflows within AEC and customisation needs will always exist. Hence, yes, as part of our core mission is to enable others to create an open ecosystem and save as much work as possible from reinventing the wheel. We’re really building something I wish i’d had back in the day!

At the same time, we’re always on the lookout for generic product improvements. From your usecase, would the google drive integration work or be valid for every speckler out there? Probably not. Nevertheless, if we abstract the problem to a user story along the lines of “attach metadata of various sorts to speckle objects outside authoring applications, with the purpose of allowing semi-non technical users to add context (like wallpapers, fire rating, etc.) to 3D models and thus engage constructively with the design process” - then i think the answer is a resounding YES.

Do note, given the development resources we have, the extra burden of long term maintenance we have (speckle 2.0 is now ~2.5 years old, and speckle overall… 7 years old!), we won’t be as fast as you!

[0]

2 Likes
7

Haha nice commenting going on there ^^

We now have another internal team interested in exploring to use Speckle for onsite inspections. Any thoughts on when and if this selection feature could make its way to the roadmap?

1 Like