Operations for RatingScales

Operations for Groupings

Operations for SkillResults

Operations for RatingScaleLevels

Operations for CustomFieldDefinitions

This guide includes:

• Step-by-step instructions

• Images

• One full tutorial video

Operations for EmploymentRelationTypes

Does AG5 support custom reports for API integration?

Yes, AG5 can support custom reports; however, this is not a standard use case. If you require a custom reporting solution, please contact our team to discuss specific requirements and feasibility.

Repository

A Repository serves as the top-level organizational container in the AG5 system. It acts as a tenant or workspace that isolates all data for a particular organization or business unit. Every other entity in the system belongs to a specific repository, identified by the repositoryID field present on virtually all objects.

Repositories enable multi-tenancy, allowing different organizations or departments to maintain completely separate skill management environments within the same AG5 instance. When integrating with the API, you must first identify or create the appropriate repository before working with any other entities. The repository has a unique code identifier and standard audit fields (createdAt, lastModifiedAt).

Employee

The Employee entity represents an individual worker within the organization whose skills, qualifications, and competencies are being tracked. Core personal information includes firstName, surname, initials, email, birthDate, and employeeNumber. The surname is the only required field, making the entity flexible for various data import scenarios.

Employees are the central subjects of the skill management system—they receive position assignments, achieve skill results, have skill plannings created for them, and can have various employment contracts and relations defined. The entity supports customValues for organization-specific fields and includes a remark field for additional notes. Each employee is uniquely identified by a UUID and belongs to a specific repository.

EmployeeUnavailability

EmployeeUnavailability records periods when an employee is not available for work or skill-related activities. This could represent leaves of absence, medical leave, parental leave, sabbaticals, or any other period where the employee is temporarily unavailable. The entity uses an activePeriod field in PostgreSQL date range format (e.g., [2023-01-01,2023-12-31)) to define the start and end dates.

The entity links to a specific employee via employeeID and can optionally include a reason field to document why the employee is unavailable. This information is valuable for workforce planning, ensuring that skill requirements and training schedules account for employee availability, and for generating accurate reports on workforce capacity.

EmploymentContract

An EmploymentContract represents a formal employment agreement between an employee and the organization for a defined time period. It links an employee (employeeID) to a contract type (contractTypeID) with a specific activePeriod that defines when the contract is in effect. This allows tracking of multiple contracts over time, including contract renewals and changes.

Employment contracts are essential for understanding an employee's formal relationship with the organization at any given point in time. They can be used to determine eligibility for training programs, skill requirements based on employment status, and to ensure compliance with contractual obligations related to certifications and qualifications. Historical contract data provides an audit trail of employment changes.

EmploymentContractType

EmploymentContractType is a reference entity that defines the categories of employment contracts available in the system. Common examples might include "Full-time Permanent," "Part-time," "Fixed-term," "Contractor," or "Intern." Each type has a unique code for programmatic reference and an internationalized name that supports multiple languages (e.g., {"en": "Full-time", "nl": "Voltijd"}).

This entity enables standardization of contract classifications across the organization and supports localized display names for multinational deployments. By maintaining a controlled vocabulary of contract types, organizations can generate consistent reports and apply business rules based on employment status, such as different skill requirements for permanent versus temporary staff.

EmploymentRelation

EmploymentRelation defines a relationship between two employees within the organization for a specified time period. It connects a fromEmployeeID to a toEmployeeID through a relationTypeID, with an activePeriod indicating when the relationship is valid. This structure supports modeling hierarchical and non-hierarchical relationships that may change over time.

Common use cases include manager-subordinate relationships, mentor-mentee pairings, team lead assignments, or any other formal relationship that affects skill management workflows. For example, a manager relationship might be used to determine who approves skill results or who is responsible for ensuring their team members maintain required certifications. The time-bounded nature allows tracking of relationship history as organizational structures evolve.

EmploymentRelationType

EmploymentRelationType is a reference entity that categorizes the types of relationships that can exist between employees. Examples include "Manager," "Mentor," "Supervisor," "Team Lead," or "Backup." Each type has a unique code and an internationalized name supporting multiple languages.

This entity provides flexibility in defining organization-specific relationship types while maintaining a controlled vocabulary. The types defined here determine what relationships can be created between employees and enable the system to apply appropriate business logic based on relationship context, such as routing approval workflows or generating organizational charts.

Grouping

A Grouping represents an organizational unit, team, department, location, project, or any other logical collection used to organize employees and skill requirements. Groupings have a code, internationalized name and description, and an activePeriod defining when the grouping is valid. They can reference a typeID (linking to GroupingType) and definedInGroupingID to create hierarchical structures.

Groupings are highly flexible and can represent various organizational concepts depending on business needs—departments, cost centers, physical locations, project teams, or competency clusters. The hierarchical capability via definedInGroupingID allows modeling of complex organizational structures like "Engineering > Backend Team > API Squad." Groupings support customValues for organization-specific attributes and play a key role in aggregating skill data and defining skill requirements at different organizational levels.

GroupingType

GroupingType is a reference entity that classifies the different kinds of groupings in the system. Examples might include "Department," "Team," "Location," "Project," or "Business Unit." Each type has a code, internationalized name, an activePeriod, and supports customValues.

By categorizing groupings with types, organizations can apply different behaviors or reporting logic based on the grouping category. For instance, "Location" groupings might trigger different compliance requirements than "Project" groupings. The typing system also improves user experience by helping users understand what kind of organizational unit they're working with.

SkillDefinition

SkillDefinition is a core entity that defines a specific skill, competency, certification, or qualification that can be tracked in the system. It includes a code, internationalized name and description, an activePeriod for when the skill is relevant, a required ratingScaleID linking to the measurement scale used, and an optional typeID for categorization.

Skill definitions form the foundation of the competency management system. They describe what capabilities or credentials the organization wants to track—from technical skills like "Python Programming" to certifications like "Forklift Operator License" to soft skills like "Leadership." Each definition specifies how proficiency is measured through its rating scale, and the active period allows retiring obsolete skills while preserving historical data. Custom values support organization-specific metadata.

SkillDefinitionType

SkillDefinitionType categorizes skills into logical groups such as "Technical Skills," "Certifications," "Soft Skills," "Safety Qualifications," or "Language Proficiency." Each type has a code, internationalized name, and supports customValues.

Typing skill definitions helps organizations organize their competency frameworks and apply different business rules based on skill category. For example, "Certification" type skills might require document uploads as proof, while "Technical Skills" might use self-assessment. The categorization also improves navigation and reporting, allowing users to filter skills by category and generate type-specific analytics.

SkillResult

SkillResult records an employee's achieved competency or completed qualification. It links an employee (employeeID) to a type of proof (typeOfProofID) with an issueDate when the achievement was recorded and an optional expirationDate for time-limited certifications. It may include a scoreID (linking to a RatingScaleLevel) to indicate proficiency level and a remark for additional context.

This entity captures the outcomes of training, assessments, and certification activities. When an employee completes a course, passes an exam, or demonstrates competency, a SkillResult is created to document the achievement. The expiration date is critical for managing certifications that require periodic renewal, enabling the system to alert users about upcoming expirations and compliance risks. Supporting documents can be attached to provide evidence of the achievement.

SkillPlanning

SkillPlanning represents a planned or in-progress skill development activity for an employee. It links an employee (employeeID) to a skill definition (skillDefinitionID) with scheduling fields: fromDate (when development begins), deadlineDate (target completion), and closeDate (actual completion). An optional typeOfProofID specifies how the skill will be demonstrated.

This entity enables proactive workforce development by tracking planned training and certification activities before they're completed. Managers can create skill plannings to schedule training for their team, track progress toward competency goals, and identify bottlenecks in development pipelines. The planning data supports gap analysis, resource allocation for training programs, and ensures employees are on track to meet compliance deadlines.

RatingScale

A RatingScale defines a measurement system used to assess proficiency levels for skills. It has a code, internationalized name, and supports customValues. Rating scales provide the framework within which skill achievements are measured and compared.

Organizations typically define multiple rating scales for different contexts—a simple "Certified/Not Certified" binary scale for compliance certifications, a Likert scale (1-5) for technical proficiency, or a Dreyfus model scale (Apprentice, Beginner, Basic, Expert, Failed) for complex skills. Each skill definition references exactly one rating scale, ensuring consistent measurement within that skill domain while allowing different scales across different skill types.

RatingScaleLevel

RatingScaleLevel defines an individual level or grade within a rating scale. It belongs to a specific ratingScaleID and includes a scoreOrder (integer determining the hierarchy), code, internationalized name and description, and supports customValues.

For a five-point proficiency scale, you might have levels with scoreOrder 1-5 representing "Apprentice" through "Expert." The scoreOrder enables sorting and comparison of proficiency levels, while the code provides a stable identifier for integrations. The internationalized name and description allow levels to be displayed appropriately in different languages and with helpful context about what each level represents in practice.

RatingScaleLevelDescriptor

RatingScaleLevelDescriptor provides skill-specific descriptions of what a rating scale level means in the context of a particular skill. It links a ratingScaleLevelID to a skillDefinitionID with an internationalized description explaining the competency expectations at that level for that specific skill.

This entity enables rich, contextual guidance for skill assessment. While a rating scale level might generically be called "Apprentice," the descriptor can explain exactly what "Apprentice" means for "Python Programming" versus "Project Management." This specificity improves assessment consistency and helps employees understand exactly what capabilities they need to demonstrate to achieve each level.

PositionAssignment

PositionAssignment links an employee to one or more tags (via tagIDs) for a specific activePeriod, representing the employee's role or position within the organization. It includes employeeID, optional remark, and supports the standard audit fields.

While the entity references "tags" rather than a separate Position entity, position assignments effectively define what roles or positions an employee holds and when. This is crucial for determining skill requirements—different positions may have different mandatory qualifications. The time-bounded nature supports tracking position history, promotions, lateral moves, and temporary assignments.

Document

The Document entity represents a file (pdf for example) attachment that can be associated with other entities, typically as evidence supporting skill results. It includes filename, contentType (MIME type), size (in bytes), and a downloadUrl for retrieving the actual file content.

Documents provide the evidentiary foundation for competency claims. When an employee uploads a certificate, diploma, training completion record, or assessment result, it's stored as a Document. The API supports uploading documents through a proposal workflow, ensuring proper validation and storage. Document management is essential for audit trails and compliance verification.

CustomFieldDefinition

CustomFieldDefinition allows organizations to extend the standard entity schemas with additional fields specific to their needs. Each definition has a code (the field name), internationalized name, and entityDefinitionID specifying which entity type the field applies to.

This extensibility mechanism enables AG5 to adapt to diverse organizational requirements without code changes. An organization might add custom fields like "Cost Center," "Union Membership," or "Security Clearance Level" to the Employee entity, or add "Training Provider" and "Course Duration" fields to skill-related entities. Custom values are then stored in the customValues map on supported entities.

EntityDefinition

EntityDefinition is a metadata entity that describes the core entity types available in the system. Each definition has an id, code (like "Employee" or "SkillDefinition"), and internationalized name. This entity enables the custom field system by providing stable references to entity types.

This serves as a registry of entity types, primarily used in conjunction with CustomFieldDefinition to specify which entity a custom field belongs to. It provides a stable contract for entity types that the customization system can reference.

MonitoringTrace

MonitoringTrace records system monitoring events with requestedAt and executedAt timestamps and an optional remark. This entity appears to support operational monitoring and audit logging within the system.

While not directly related to skill management, monitoring traces provide operational visibility into system activities. They can be used to track when batch processes run, record integration events, or maintain audit trails for compliance purposes. The timestamps enable measuring execution performance and identifying processing delays.

Error

While not a business entity, the Error schema defines the standard error response format across the API. It includes a machine-readable code (such as INVALID_INPUT, NOT_FOUND, RATE_LIMIT_EXCEEDED), human-readable message, optional details object, and requestId for support troubleshooting.

This standardized error format ensures consistent error handling across all API consumers and supports both programmatic error processing and human debugging. The error codes enable applications to implement appropriate retry logic or user messaging based on the error type.

Cross-Cutting Concepts

Proposals: The API uses a proposal pattern for data modification, where changes are submitted as proposals that may require approval before being executed. This supports workflow controls and audit trails.

Internationalization (IString): Text fields that support multiple languages use an object format with language codes as keys (e.g., {"en": "English text", "nl": "Dutch text"}).

Active Periods: Many entities use PostgreSQL-style date ranges [start,end) to define when records are valid, supporting temporal data management and historical tracking.

Custom Values: Most entities support a customValues map for organization-specific fields defined through CustomFieldDefinition.