3CX icon

3CX

Interact with 3CX telephony system
Join our community

Actions462

Overview

This node operation lists Service Principals from a connected service, allowing users to retrieve multiple service principal records with flexible query options. It is useful in scenarios where you need to manage or audit service principals programmatically, such as fetching all service principals for an organization, filtering by specific criteria, or paginating through large sets of data.

Practical examples include:

  • Retrieving the first 10 service principals created in the last month.
  • Searching service principals by name or other attributes.
  • Filtering service principals based on their state or other properties.
  • Selecting only specific fields to reduce payload size.

Properties

Name Meaning
Options A collection of optional query parameters to customize the list request:
$top Show only the first n items (pagination limit).
$skip Skip the first n items (pagination offset).
$search Search items by search phrases. If the phrase contains spaces and is not quoted, it will be auto-quoted.
$filter Filter items by property values using OData filter syntax (e.g., State eq 'Connected').
$count Include count of total matching items (boolean).
$orderby Order items by property values (e.g., Name desc, CreatedAt asc).
$select Select specific properties to be returned (comma-separated list).
$expand Expand related entities (comma-separated list).

Output

The output JSON field contains an array of service principal objects retrieved according to the specified query options. Each object represents a service principal with its properties as returned by the API. The exact structure depends on the selected fields and expansions but typically includes identifiers, names, states, and related entity information.

If binary data were involved (not indicated here), it would represent attachments or files related to service principals, but this operation focuses on JSON data only.

Dependencies

  • Requires an authenticated connection to the target service that manages service principals.
  • Needs an API key or OAuth2 token configured in the node credentials to authorize requests.
  • The base URL for the API is dynamically set from the credential's server URL configuration.

Troubleshooting

  • Empty results: Check if filters or search queries are too restrictive or incorrectly formatted.
  • Authentication errors: Ensure the API key or OAuth2 token is valid and has sufficient permissions.
  • Invalid query parameters: Verify that OData filter, orderby, select, and expand strings follow correct syntax.
  • Pagination issues: When using $top and $skip, ensure values are numeric and within allowed ranges.
  • API rate limits: If many requests are made quickly, the API might throttle; implement retries or delays.

Links and References

Discussion