Adapter Actions advanced parameters

Note

This page can be seen as an Appendix to the pages Introduction to BHoM_Adapter and Adapter Actions.

As it can be noted, the Adapter Actions have some particular input parameters:

• the ActionConfig (used by all Actions: Push, Pull, Move, Remove, Execute);
• the Data Tags (used by most Actions: Push, Pull, Move, Remove)
• the Requests (used by the Pull)

ActionConfig

The ActionConfig is an object type used to specify any kind of Configuration that might be used by the Adapter Actions.

This means that it can contain configurations that are specific to certain Actions (e.g. only to the Push, only to the Pull), and that a certain Push might be activated with a different Push ActionConfig than another one. This makes the ActionConfig different from the Adapter Settings (which are static global settings).

The base ActionConfig provides some configurations that are available to all Toolkits (you can find more info about those in the code itself).

You can inherit from the base ActionConfig to specify your own in your Toolkit. For example, if you are in the SpeckleToolkit, you will be able to find:

• SpecklePushConfig: inherits from ActionConfig
• SpecklePullConfig: inherits from ActionConfig

this allows some data to be specified when Pushing/Pulling.

ActionConfig is an input to all Adapter methods, so you can reference configurations in any method you might want to override.

Data Tags

When objects are pushed, it is important to have a way to know which objects they are replacing (if any). If the number of objects changes between pushes, you cannot rely on unique identifiers or other solutions that match the objects one-to-one. The problem is especially clear when you are pushing less objects than the last push. Attaching a unique tag to all the objects being pushed as a group is a lightweight and flexible way to find those objects later. For those using D3.js, it is equivalent to attaching a class to html elements. For those using Mongo or Flux, this is similar to the concept of key.

Keep in mind that some objects might end up with multiple tags. For example, if I push a set of bars to a structural analysis software with the tag "bars1", everything that those bars need to be fully defined will be pushed as well (i.e. the nodes, section properties, materials,...). Let's say I now push another set of bars corresponding to an adjacent part of the building with the tag "bars2", it might be that some of the nodes, section properties and materials will be common between those two groups. The common elements will therefore end up with two tags on them. If I then delete the elements with the tag "bars1", only the tag "bars2" will remain".

At the moment, each external software will likely require a different solution to attach those tags to the objects. If the software doesn't provide any solution to group objects or tag them, most of them provide a Name that can be used to save both the BHoM name of the object followed by the tags. The convention we are using for that is "Name Tags:tag1_/tag2/_tag3" for an object that has 3 tags attached to it. This is obviously a bit of a hack and will be replaced by a more permanent solution when databases (i.e. Mongo) become more mainstream as a workflow. Tags will then be stored on a database along with other relevant information such as object's history every time an object is being pushed to any adapter.

Requests

Requests are an input to the Pull adapter Action.

They were formerly called Queries and are exactly that: Queries. You can specify a Request to do a variety of things that always involve Pulling data in from an external application or platform. For example:

• you can Request the results of an FE analysis from a connected FEM software,
• specify a GetRequest when using the HTTP_Toolkit to download some data from an online RESTFul Endpoint
• query a connected Database, for example when using Mongo_Toolkit.

Requests can be defined in Toolkits to be working specifically with it.

You can find some requests that are compatible with all Toolkits in the base BHoM object model. An example of those is the FilterRequest.

The FilterRequest is a common type of request that basically requests objects by some specified type. See FilterRequest.

In general, however, Requests can range from simple filters to define the object you want to be sent, to elaborated ones where you are asking the external tool to run a series of complex data manipulation and calculation before sending you the result.

Additional note: batch requests

For the case of complex queries that need to be executed batched together without returning intermediate results, you can use a BatchRequest.

Additional note: Mongo requests

For those that use Mongo already, you might have noticed how much faster and convenient it is to let the database do the work for you instead doing that in Grasshopper. It also speeds up the data transfer in cases where the result is small in bytes but involves a lot of data to be calculated.