Registering Entities
Overview
Registering an entity moves the entity into the organization’s Registry. Entities in the Registry are validated and shared among the other members of the organization.
There are three ways to register an entity with the API:
- Create and register in one call, with the V3 create endpoints for each entity type, such as
POST /api/v3/dna-oligo,POST /api/v3/custom-entity, and their:batch-createand:bulk-createvariants. - Register existing entities with the V3 update endpoints, such as
PATCH /api/v3/dna-oligo/{id},PATCH /api/v3/custom-entity/{id}, and their:batch-updateand:bulk-updatevariants. - Register existing entities of mixed types in a specific registry with the V2 Bulk register entities endpoint.
The first two approaches use the V3 Python SDK. The same registryId, namingStrategy, and entityRegistryId fields exist on DNA sequences, AA sequences, RNA sequences, oligos, molecules, and proteins. The third approach has no V3 equivalent: V3 has no registry-scoped bulk registration endpoint, and /api/v3/registry is read-only. That section stays on V2.
The V3 custom entity endpoints are stable. The V3 DNA oligo, DNA sequence, AA sequence, and registry endpoints are beta. Set early_access="true" on the client, as in the examples below, or send the EARLY-ACCESS: true header on raw HTTP requests. See the V3 Stability Guidelines.
Enable Higher Registry Performance
If you are having issues with registry locks and / or performance when registering items in Benchling, please reach out to Benchling support and ask about granular locking for the Registry.
Your Benchling representative can change the configuration of your Registry to allow for more parallel registration attempts which will also increase total throughput.
Every example below uses this client. Pass your tenant’s root URL; the SDK adds /api/v3 itself.
To register, you need the ID of the registry. The registryId must match the registry of the entity’s schema. Copy it from the UI, or look it up by name:
Our registry ID is src_JK1ktG3S.
Create endpoints
Entities can be created directly in the registry. To do this, pass registry_id (registryId in the request body). When an item is added to the registry, it receives a new ID called the entityRegistryId. The entityRegistryId can be provided directly with the entity or it can be generated automatically based on a naming strategy. To use the automatically generated names, provide a namingStrategy instead of the entityRegistryId; the two cannot be set together.
A :batch-create request creates up to 25 entities in a single transaction: if any entity fails validation, none are created and the errors describing the invalid entities are returned. For larger sets, use :bulk-create; see Bulk Import. As in V2, every entity in one :batch-create or :bulk-create request must use the same registryId and namingStrategy; split entities that need different ones into separate requests.
Example To create a DNA oligo and have an entityRegistryId generated for us:
The SDK sends this request body to POST /api/v3/dna-oligo:
The response is the created oligo. Its entityRegistryId holds the generated registry ID, and its registry names the registry it now belongs to.
Update endpoints
Existing entities can be registered by calling the update endpoint for their entity type with a registryId, plus either a namingStrategy or an entityRegistryId. On an entity that is already registered, setting entityRegistryId changes its registry ID, and setting registryId to null unregisters it.
To register up to 25 entities of one type in a single transaction, use :batch-update. This example registers two DNA sequences with the IDS_FROM_NAMES naming strategy:
For more than 25, write one {"request_id": ..., "input_object": {"id": ..., "registryId": ..., "namingStrategy": ...}} line per entity to a JSONL scratch file and call :bulk-update, as described in Bulk Import.
Bulk register endpoint
This endpoint is V2 only, and V3 won’t get a direct replacement. It registers existing entities of any type in one call, by specifying the IDs of the entities as the value for param entityIds and a value for param namingStrategy. In V3, the intended path is to group the entities by type and register each group by setting registryId with that type’s :batch-update or :bulk-update, as shown above.
This endpoint will first check that the entities are all valid to be moved into the registry given the namingStrategy. If any entities fail validation, no files will be moved and errors describing the invalid entities are returned. Only if all entities pass validation are the entities moved into the registry.
Example Moving two entities to a registry identified by src_JK1ktG3S, using the IDS_FROM_NAMES naming strategy:
The returned value in this example is a task ID that will complete in the background. If you need to check on its status, call the V2 tasks endpoint for it:
The status field in the response will be SUCCEEDED if the task completes successfully.
Naming Strategies
The naming strategy specifies the behavior for how to name an entity and how to generate its registry ID when registering it.
Registration Attempt Error
Benchling cannot always process two registration attempts within the same registry at the same time, so it’s possible for the task to return an error response that indicates another attempt is already in progress and currently blocking this one. Benchling will automatically retry the task up to 3 times, and in the unlikely event that it is still failing, the task status will be FAILED and the error message will read:
Another registration attempt is in progress. Please try again in a few moments. If this problem persists, please wait 1-2 minutes before trying again.
Using Registration Events
Once an entity is registered, you can listen to the entity.registered event over our events system and add your own automation or logic to the registration of an entity. Some examples:
- Fill in extra schema fields
- Add metadata from external systems
- Link other entities
Merging Duplicates
In some cases, Benchling will merge entities that are considered duplicates of existing registered entities. For information on when this will occur, check out our help article.
When this case is encountered in the API, it will prompt that it needs a folder for the duplicate to live in: