Custom Attributes in Onboarding

In Onboarding, you can create custom attributes for core entities, including employees, employers, clients, placements, and forms. These attributes function like custom fields, helping you categorize records, filter data, and support advanced configuration needs. This article explains how to create custom attributes and how they are used within the system.

NOTE: Custom attributes do not control role-based access. They can be used in filters and views, but they do not grant or restrict user permissions.

Use Cases

• Storing additional employee information.
• Adding classification fields for clients or employers.
• Capturing placement-specific details.
• Extending onboarding form data requirements.

Create a Custom Attribute

Within Onboarding, select Settings.

Click Organization Settings.

Click Custom Attributes.

Click New Custom Attribute.

The Create a new custom attribute page is displayed. NOTE: The example below shows how to create an employee custom attribute. If your use case requires managing access for multiple entities, please create a custom attribute for each entity.

Fill out the following fields:

• Entity – Select from Employee, Employer, Client, Placement, or Form.
• Name - Name determines how this attribute can be set and returned from the entity API. For example, when working with employee custom attributes, add the prefix `employee.custom_attributes.` to the property name in the field path. The same prefix is needed when setting and reading submissions for fields under this property via the Task API. When working with employer custom attributes, use the prefix `employer.custom_attributes.` instead.
• Scalar Type – Select from String, Boolean, Date, Datetime, or Integer.
• Label - The name shown in the core entity New/Edit form. Choose a clear value that describes the information this attribute captures.
• Description - Description will be displayed as a hint in the core entity new/edit form next to the input that collects the value for this custom attribute. Use this field to help you understand the appropriate value you should enter for this custom attribute.
• Searchable - Please make sure to check both boxes for Searchable and Permission Scope so that the attribute can be used as a filter and in access rules when defining permissions.
• Sensitive Information - Sensitive information will be masked and can be revealed by clicking. If the Core Entity API Resource is enabled, sensitive information will be included in the core entity API response.
• Permission Scope - All custom attributes used for access management must be marked as a Permission Scope when they are created or updated. This is important for several reasons:
  • Not all attribute configurations are suitable for use with permissions. For example, custom attributes marked as Sensitive Information may be encrypted and stored separately, making them unsuitable for access validation.
  • When configuring permissions, you can only select from a list of custom attributes that have permission scope enabled. This helps you to select the right custom attributes when building your access rules, as accounts can easily have hundreds of custom properties.

When you’re finished filling out the fields, click Create Custom Attribute.

Once created, custom attributes can be added to forms, reporting views, search filters, and task configurations depending on their type.

For example, you can set the Service Region when creating or editing employees.

API Example

Below is an example of how to set a custom attribute on employee creation using the API:

You can set this custom attribute when creating/updating records of this entity. The example below demonstrates how to provide a service region when creating employees.

curl -i -X POST \
  https://app.onboarded.com/api/v1/employees \
  -d '{
    "name": "Brad Marchand",
    "custom_attributes": [
      "service_region": "US East",
    ],
    ...
  }'