This guide defines what an agent is, what types of agents there are in Specify, and what role agents play in data attribution. It also explains what data is stored with an agent, what roles agents play in transactions, and how âGroupâ and âOrganizationâ agents are structured.
Understanding Agents in Specify
In Specify, the Agent record is one of the most fundamental and versatile concepts. An Agent is not just a person; itâs the central record used to store information about any person, group, or organization that interacts with your collection data. Properly managing Agent records is key to tracking attribution, contact information, and relationships throughout your database.
Agents are specific to each division, see Specify Institutional Scopings for more information.
Types of Agents
Every Agent record is defined by a type, which determines how itâs used:
-
Person: This is the most common type, representing an individual. Person records are used to attribute activities like collecting, identifying, preparing, or donating specimens. They store personal details such as first and last names, job titles, and contact information.
-
Organization: This type represents a formal institution, agency, or company. Examples include universities, museums, government bodies, or funding agencies. Organizations can be structured hierarchically; for instance, you can create an Agent for a university and another for a specific department, linking the department to its parent university.
-
Group: This type is used to represent a collection of individuals, such as an expedition team, a committee, or a family. A âGroupâ agent is essentially a container that can be linked to multiple âPersonâ agents. This is useful when you need to credit an entire team for a collecting event without listing each member individually every time.
-
Other: This type includes any agent that does not conform to the previous definitions. This is the least common type.
Information Stored with an Agent
Beyond the basic name and type, an Agent record serves as a hub for related information, providing a complete profile:
- Addresses: An agent can have multiple addresses (e.g., mailing, shipping, office) with start and end dates.
- Identifiers: You can store unique, persistent identifiers for agents, such as an ORCID, Wikidata, or other global or institutional IDs. This is crucial for linking data across different systems.
- Specialties: You can list their areas of taxonomic or scientific expertise.
- Variant Names: This allows you to record alternate names, such as aliases, former names, or names in different languages.
- Attachments: You can attach files directly to an Agent record, such as a CV, a photograph, or scanned correspondence.
The Role of Agents in Data Attribution
The primary function of Agents is to provide attribution. Nearly every record in Specify that documents an actionâfrom creating a record to collecting a specimenâis linked to an Agent. This creates a detailed history of who did what and when.
Common roles for Agents include:
- Collector on a Collecting Event
- Determiner for a taxonomic identification
- Preparator of a specimen
- Donor or contact on an Accession
- Borrower or Lender on a Loan transaction
- Creator (
CreatedByAgentID) and Modifier (ModifiedByAgentID) of any data record
By consistently using and linking to Agent records, you ensure your collection data is rich with the history and context of the people and institutions who built and managed it. As a best practice, always search for an existing Agent before creating a new one to avoid creating duplicates. If duplicates are introduced, administrators can use the Record Merging tool to reconcile duplicates.
Agents in Transactions
Beyond simple attribution, Agents are essential for managing complex transactions like loans and gifts, which often involve multiple parties. Specify handles this using dedicated linking tables that define the role each agent plays.
When you create a Loan or Gift record, you donât just link to one agent; you can link to many. Tables like loanagent and giftagent connect the transaction record to different Agent records, each with a specific role.
For example, on a single Loan, you can have:
- An Organization Agent with the role of âLenderâ.
- A Person Agent (the curator at that organization) with the role of âAuthorized Byâ.
- Another Organization Agent with the role of âBorrowerâ.
- Another Person Agent with the role of âRecipientâ.
How Group & Organization Agents are Structured
The power of âGroupâ and âOrganizationâ agents comes from how they are associated with other agents in the database.
Organizations and Hierarchies
Organizational structures are created through a direct relationship within the agent table itself. You can add a field called Organization to the Agent form. This field can link one agent to another agent that is an âOrganizationâ type.
This creates a parent-child hierarchy, which is useful for modeling real-world structures:
- A Person agent for a staff member can have their employer as the âOrganizationâ (link to another Agent record).
- An Organization agent for a university department can have the universityâs main record as its"Organization" (link to another Agent record).
This structure allows you to build out a full institutional hierarchy and see all the people and sub-units associated with an organization.
Groups and Memberships
Group associations are managed using a dedicated linking table called âGroup Personâ. This table creates a many-to-many relationship between âGroupâ type agents and âPersonâ type agents. The âGroup Personâ table links the agent with the appropriate agent âGroupâ.
A person can be a member of multiple groups, and a group can have many members. When you attach a âGroupâ agent as the collector on a collecting event, you are implicitly associating all of its members with that event as well.