Introduction to the BHoM_Adapter
Before reading this page, have a look at the following pages:
and make sure you have a general understanding of:
In this page you will find a first overview about what is the BHoM Adapter.
- What is an adapter?
- The Adapter Interface
- Your Toolkits' Adapter extends the base BHoM_Adapter
- Adapter Actions
- Next steps
As shown in the Structure of the BHoM framework, an adapter is the piece of code responsible to actuate the connection (import/export) between different software packages.
The Base BHoM_Adapter includes a series of methods that are common to all software connections. Specific Adapter implementations are included in what we call the Toolkits.
We will see how to create a Toolkit later; however consider that, in general, a Toolkit is simply a Visual Studio solution that can contain one or more of the following:
- A BHoM_Adapter project, that allows to implement the connection with an external software.
- A BHoM_Engine project, that should contain the Engine methods specific to your Toolkit.
- A BHoM_oM project, that should contain any oM class (types) specific to your Toolkit.
The BHoM_Adapter is one of the base repositories, with one main Project called BHoM_Adapter.
This project takes care of the backing actions needed to link a software to another software. It's the core communication interface that the BHoM exposes to allow for information interchange between different software packages.
It's important to keep in mind that the BHoM_Adapter should be seen as the background helper to connect between different software.
This is because when you actually want to implement a new software connection, or work on an existing one, you will have to create and work not on the BHoM_Adapter, but on a specific Toolkit.
This important aspect needs to be understood here:
when you want to create the connection between the BHoM and another software, you will have to create what is called a Toolkit. A Toolkit is yet another repository that contains a Visual Studio solution. A Toolkit is backed by (meaning that it contains, or better, extends) the BHoM_Adapter.
A Toolkit can be seen as the a concrete implementation of the BHoM_Adapter, meaning that it's the piece of code that actually implements the connection between different software.
You can read more on the Toolkit here.
First and foremost feature of the BHoM_Adapter are the Adapter Actions.
The Actions are your "portal" towards different external software. You will be able to export, import and much more with them.
The Adapter Actions, like all the rest of the BHoM, are always the same no matter what User Interface program you are using (Grasshopper, Excel, Dynamo...). In Grasshopper, there will be a component representing each action; in Dynamo, a node for each of them; in Excel, a formula will let you use them.
To see them in their UI context, taking the example of Grasshopper, you can find these methods in the Adapter subcategory:
Let's have an overview of the actions.
The following is a brief overview, more than enough for any user.
A more in-detail explanation, for developers and/or curious users, is left in the next page of this wiki.
The first thing to understand is that the Adapter Actions do different things depending on the software they are targeting.
In fact, the first input to any Adapter Action is always an Adapter, which targets a specific external software or platform. The first input Adapter is common to all Actions.
The last input to any Adapter action is an active Boolean, that can be True or False. If you insert the value True, the Action will be activated and it will do its thing. False, and it will sit comfortably not doing anything.
The most commonly used actions are the Push and the Pull. You can think of Push and Pull as Export and Import: they are your "portal" towards external software.
Again, taking Grasshopper UI as an example, they look like this (but they always have the same inputs and outputs, even if you are using Excel or Dynamo):
The Push takes the input objects and:
- if they don't exist in the external model yet, they are created brand new;
- if they exist in the external model, they will be updated (edited);
- under some particular circumstances and for specific software, if some objects in the external software are deemed to be "old", the Push will delete those.
This method functionality varies widely depending on the software we are targeting. For example, it could do a thing as simple as simply writing a text representation of the input objects (like in the case of the File_Adapter) to taking care of object deletion and update (GSA_Adapter).
In the most complete case, the Push takes care of many different things when activated: ID assignment, avoiding object duplication, distinguishing which object needs updating versus to be exported brand new, etc.
The Pull simply grabs all the objects in the external model that satisfy the specified request (which simply is a query).
If no request is specified, depending on the attached adapter, it might be that all the objects of the connected model will be input, or simply nothing will be pulled. You can read more about the requests in the Adapter Actions - advanced parameters section.
Now, let's see the remaining "more advanced" Adapter Actions.
Again taking Grasshopper as our UI of choice, they look like this:
Let's see what they do:
-
Move: This will copy objects over from a
sourceconnected software to anothertargetsoftware. It basically does a Pull and then a Push, without flooding the UI memory with the model you are transferring (which would happen if you were to manually Pull the objects, and then input them into a Push – between the two actions, they would have to be stored in the UI). - Remove: This will delete all the objects that match a specific request (essentially, a query). You can read more about the requests in the Adapter Actions - advanced parameters section.
- Execute: This is used to ask the external software to execute a specific command such as Run analysis, for example. Different adapters have different compatible commands: try searching the CTRL+SHIFT+B menu for "[yourSoftwareName] Command" to see if there is any available one.
You might have noticed that the Adapter Actions take some other particular input parameters that need to be explained: the Requests, the ActionConfig, and the Tags.
Their understanding is not essential to grasp the overall mechanics; however you can find their explanation in the Adapter Actions - Advanced parameters section of the wiki.
The Adapter Actions have been designed using particular criteria that are explained in the next Wiki page. Most users might be satisfied in just knowing that they have been developed like this so they can cover all possible use cases, while retaining ease of use.
More detail can be read in the next pages, but that's not needed unless you are a developer or a very avid reader.
Otherwise, try some of the Samples and you should be good to go! 🚀
When you want to contribute to the BHoM and create a new software connection, you will not need to implement the Adapter Actions, at least in most of the cases.
If you need to, however, you can override them (more details on that in last page of this Wiki, where we explain how to implement an Adapter in a new BHoM Toolkit).
So what is it that you need to implement?
The answer is: the so called CRUD Methods. We will see them in the next page.
Proceed to get a better understanding of the Adapter Actions and their backing CRUD methods.