Actions88
- Module Actions
- Platform Actions
- Device Actions
- Device Bay Actions
- Device Bay Template Actions
- Device Role Actions
- Device Type Actions
- Interface Actions
- Manufacturer Actions
- Module Bay Actions
- Module Bay Template Actions
- Module Type Actions
- Region Actions
- Site Actions
- Virtual Chassis Actions
- Virtual Device Context Actions
Overview
This node integrates with the NetBox API, specifically allowing users to list Device Roles within the DCIM domain. It is useful for retrieving metadata about device roles defined in a NetBox instance, which can help in network infrastructure management, automation, and reporting.
Typical use cases include:
- Fetching all device roles to populate dropdowns or selection lists in workflows.
- Filtering device roles by attributes such as name, slug, color, VM role status, or tags.
- Automating inventory or configuration tasks based on device role classifications.
For example, a user might want to retrieve all device roles tagged as "core" to apply specific configurations only to core network devices.
Properties
| Name | Meaning |
|---|---|
| Domain | The NetBox API domain to target. Options: DCIM, IPAM, Tenancy, Extras, Virtualization, Circuits, Core, Users, Plugins, VPN, Wireless, Status. For this operation, must be "DCIM". |
| Return All | Whether to return all results or limit the number of returned items. |
| Limit | Maximum number of results to return if "Return All" is false (1 to 1000). |
| Filters | Collection of filters to narrow down the list of device roles: |
| Name | Filter by device role name (string). |
| Slug | Filter by slug (string). |
| Color | Filter by color hex code (string). |
| VM Role | Filter by VM role status (boolean). |
| Tag | Filter by tag (string). |
Output
The node outputs an array of JSON objects representing device roles retrieved from the NetBox API. Each object contains the properties of a device role as defined by NetBox, such as its name, slug, color, VM role status, and tags.
The output does not include binary data.
Example output snippet (simplified):
[
{
"id": 1,
"name": "Server",
"slug": "server",
"color": "#ff0000",
"vm_role": false,
"tags": ["core", "critical"]
},
{
"id": 2,
"name": "Virtual Machine",
"slug": "virtual-machine",
"color": "#00ff00",
"vm_role": true,
"tags": []
}
]
Dependencies
- Requires an API key credential for authenticating with the NetBox API.
- The node depends on the external NetBox API service being accessible.
- No additional environment variables are required beyond the API authentication setup.
Troubleshooting
Common issues:
- Authentication failures due to invalid or missing API credentials.
- Network connectivity problems preventing access to the NetBox API endpoint.
- Using filters that do not match any device roles, resulting in empty output.
- Exceeding rate limits imposed by the NetBox API.
Error messages:
- Errors during execution are logged and, if "Continue On Fail" is enabled, returned as error objects in the output.
- Typical error messages include HTTP errors (401 Unauthorized, 404 Not Found) or timeout errors.
Resolutions:
- Verify API credentials and permissions.
- Check network connectivity and API endpoint URL.
- Adjust filters to valid values.
- Enable "Return All" cautiously to avoid large data loads.