Skip to content
Reference

SDK query migration reference

Look up the replacement for an existing directory or approval call and see when to keep the host method.

SDK query migration reference

What you are doingUse
Read, filter or join directory rowsParty::query(), User::query(), LegalEntity::query(), OperatingUnit::query() or Site::query()
Read approvals for the current userApproval::query($legalEntity) with paginate(), first() or find()
Check access or current eligibility, submit an approval, or reconcile an outcomeThe corresponding existing host contract

The models live in Nexia\Laravel\Directory. Use them with a compatible PHP SDK and Core on a managed App database or a developer-local snapshot prepared by the matching CLI. Keep the App's record policy when joining, and keep the existing host contract when a caller-specific visibility decision or fresh data is needed. On customer-managed App databases use the host contracts. Model methods return Eloquent models, scalars or collections. A required lookup raises the new model's Eloquent exception. Keep the host lookup when the calling code needs the original platform object.

Rows that keep the existing API explain when it is needed. Check the required visibility and return type before moving a call. Review remaining callers and supported runtimes before removing a method.

See Resource References for the deprecated IdentityQueries compatibility note.

See Reference Core identities from App tables for setup and joins and Electronic Approval contracts for fields, visibility and linked App record filters.

Party

TaskPrevious APIAPI to use
Find by public IDPartyDirectory::findByPublicId($id)Party::where('public_id', $id)->first()
Require a public-ID matchPartyDirectory::requireByPublicId($id)Party::where('public_id', $id)->firstOrFail()
Check whether a public ID existsPartyDirectory::exists($id)Party::where('public_id', $id)->exists() For access decisions, use PartyAccess::allows().
Find several public IDsPartyDirectory::findByPublicIds($ids)Party::whereIn('public_id', $ids)->get()->keyBy('public_id')->all() Keeps the public-ID map. Values are Eloquent models.
Find by keyPartyDirectory::findByKey($key)Party::find($key)
Find by several keysPartyDirectory::findByKeys($keys)Party::whereKey($keys)->get()->all()
Require a key matchPartyDirectory::requireByKey($key)Party::findOrFail($key)
Read the public ID for a keyPartyDirectory::publicIdByKey($key)Party::whereKey($key)->value('public_id')
Read public IDs by keyPartyDirectory::publicIdsByKeys($keys)Party::whereKey($keys)->pluck('public_id', 'key')->all()
Resolve the surviving Party after a mergePartyDirectory::findCanonicalByPublicId($id)Party::canonical($id) Uses the host to follow merges. Returns a model with basic fields.
Search active Party namesPartyDirectory::activeSearch($search, $limit)Party::active()->when($search !== '', fn ($q) => $q->matchingName($search))->orderBy('display_name')->limit($limit)->get()->all()
Search active Parties with caller-specific visibilityPartyDirectory::activeSearch($search, $limit)Existing method
Look up an active person by emailPartyDirectory::activePeopleByEmail($email, $limit)Party::peopleByEmail($email, $limit) Uses the same host lookup and returns a collection of models.
Search for people, including by emailPartyDirectory::searchActivePeople($search, $limit, $excludedKeys)Party::searchPeople($search, $limit, $excludedKeys) Keeps email search and exclusions. Returns models with contact_email in place of PersonDirectoryEntry objects.
Sort App rows by Party namePartyDirectory::orderByDisplayLabel($builder, $partyKeyColumn, $direction)leftJoinSub() Join Party and order by display_name.
Sort App rows with caller visibility or across connectionsPartyDirectory::orderByDisplayLabel($builder, $partyKeyColumn, $direction)Existing method
Filter App rows by Party namePartyDirectory::whereDisplayLabelMatches($builder, $partyKeyColumn, $search)whereIn($partyKeyColumn, Party::matchingName($search)->select('key'))
Filter App rows with caller visibility or across connectionsPartyDirectory::whereDisplayLabelMatches($builder, $partyKeyColumn, $search)Existing method
Resolve merged Parties in a batchBatchCanonicalPartyDirectory::findCanonicalByPublicIds($ids)Party::canonicalMany($ids) Uses batch lookup when available and individual lookups otherwise. Returns a model collection.
Look up people by multiple emailsBatchPartyDirectory::activePeopleByEmails($emails, $limitPerEmail)Party::peopleByEmails($emails, $limitPerEmail) Returns model collections keyed by normalized email. Requires the batch host contract.
Read roles by PartyPartyBusinessDirectory::activeRoles($actor, $ids)Party::roles($actor, $ids) The public-ID map becomes a collection.
Search Parties by role and typePartyBusinessDirectory::search($actor, $search, $roles, $types, $page, $perPage)Party::searchByRoles($actor, $roles, $search, $types, $perPage, $page) Check argument order. Returns a Paginator. For SQL composition use Party::withRoles($actor, $roles), which has a 10,000-match limit.
Read relationships by PartyPartyBusinessDirectory::activeRelationships($actor, $ids)Party::relationships($actor, $ids) The public-ID map becomes a collection.
Read one visible relationshipPartyRelationshipDirectory::findVisibleByPublicId($actor, $id)Party::relationship($actor, $id) Uses the same actor-aware host lookup and returns the same nullable DTO.
Decide whether the actor can access a PartyPartyAccess::allows($actor, $partyKey)Keep the existing method Keep for a caller-specific access decision.

Contracts still used for this feature

ContractExisting methods
PartyWritePreconditionsregister()
PersonPartyProvisionerensureForDirectorySubject()

User accounts

TaskPrevious APIAPI to use
Find by key, including deleted accounts if requestedActorDirectory::findByKey($key, $includeDeleted)$key === null ? null : User::withTrashed($includeDeleted)->find($key)
Find by several keysActorDirectory::findByKeys($keys, $includeDeleted)User::withTrashed($includeDeleted)->whereKey($keys)->get()->all()
Require a key matchActorDirectory::requireByKey($key, $includeDeleted)User::withTrashed($includeDeleted)->findOrFail($key)
Find by public IDActorDirectory::findByPublicId($id)User::where('public_id', $id)->first()
Require a public-ID matchActorDirectory::requireByPublicId($id)User::where('public_id', $id)->firstOrFail()
Find the first account for a PartyActorDirectory::findByPartyKey($partyKey)User::where('party_key', $partyKey)->orderBy('key')->first() Ascending key preserves the first-account selection.
Read a key from the public IDActorDirectory::keyByPublicId($id)User::where('public_id', $id)->value('key')
Read a public ID by keyActorDirectory::publicIdByKey($key)User::whereKey($key)->value('public_id')
Read public IDs by keyActorDirectory::publicIdsByKeys($keys)User::whereKey($keys)->pluck('public_id', 'key')->all()
Read the display labelActorDirectory::displayLabelByKey($key)User::whereKey($key)->value('display_label') The model falls back to the public ID when the Party label and user name are missing. The host may return the email.
Check whether an account key existsActorDirectory::existsByKey($key, $includeDeleted)User::withTrashed($includeDeleted)->whereKey($key)->exists()
Find accounts by public IDsBatchActorDirectory::findByPublicIds($ids)User::whereIn('public_id', $ids)->get()->all() Keep the host batch when an Actor[] is required.
Show one active account in a legal entityActorDirectory::activeByPublicIdForLegalEntity($id, $entityKey)User::activeForLegalEntity($entityKey)->where('public_id', $id)->first()
Verify current eligibility for a specific accountActorDirectory::activeByPublicIdForLegalEntity($id, $entityKey)Existing method. Get the live single-account decision and Actor.
List active accounts in a legal entityActorDirectory::activeForLegalEntity($entityKey)User::activeForLegalEntity($entityKey)->orderBy('display_label')->orderBy('key')->get()->all() Returns User models. SQL ordering can differ from the host’s natural sort.

Contracts still used for this feature

ContractExisting methods
PersonLoginAccountsensure()
PersonLoginInvitationsstatus(), invite()
BatchPersonLoginInvitationsstatuses()
TaskPrevious APIAPI to use
Find by public IDOrganizationDirectory::findLegalEntity($id)LegalEntity::where('public_id', $id)->first()
Require a public-ID matchOrganizationDirectory::legalEntity($id)LegalEntity::where('public_id', $id)->firstOrFail()
Find an active entity by public IDOrganizationDirectory::findActiveLegalEntity($id)LegalEntity::active()->where('public_id', $id)->first() The model’s active() requires an active entity with an organization Party. Core’s old active filter checks entity status.
Find an active entity by keyOrganizationDirectory::findActiveLegalEntityByKey($key)LegalEntity::active()->find($key) The model’s active() requires an active entity with an organization Party. Core’s old active filter checks entity status.
Find by keyOrganizationDirectory::findLegalEntityByKey($key)LegalEntity::find($key)
Find by several keysOrganizationDirectory::findLegalEntitiesByKeys($keys)LegalEntity::whereKey($keys)->get()->all()
Require a key matchOrganizationDirectory::requireLegalEntityByKey($key)LegalEntity::findOrFail($key)
Read the public ID for a keyOrganizationDirectory::legalEntityPublicIdByKey($key)LegalEntity::whereKey($key)->value('public_id')
Read a key from the public IDOrganizationDirectory::legalEntityKeyByPublicId($id, $activeOnly)LegalEntity::where('public_id', $id)->when($activeOnly, fn ($q) => $q->active())->value('key') The model’s active() requires an active entity with an organization Party. Core’s old active filter checks entity status.
Read public IDs by keyOrganizationDirectory::legalEntityPublicIdsByKeys($keys)LegalEntity::whereKey($keys)->pluck('public_id', 'key')->all()
Read a hierarchy revisionOrganizationDirectory::legalEntityHierarchyRevisionByKey($key)$entity->hierarchyRevision() On an already-loaded model. Calls the existing host method. Core and Manager currently return null.
List legal entitiesOrganizationDirectory::legalEntities()LegalEntity::orderBy('code')->get()->all() Keep the authorized target resolver for selectable entities.

Contracts still used for this feature

ContractExisting methods
HasLegalEntityProfilelegalProfile()
HasFunctionalCurrencyfunctionalCurrencyCode(), functionalCurrencyMinorUnit()
OrganizationMembershipsactorParticipatesInLegalEntity()
OrganizationTargetResolverresolveListTargets(), resolveCreateTarget()
PersonLegalEntityAccessend()

Operating units

TaskPrevious APIAPI to use
Find by public IDOrganizationDirectory::findOperatingUnit($id)OperatingUnit::where('public_id', $id)->first()
Require a unit affiliated with a legal entityOrganizationDirectory::operatingUnit($id, $entityKey)OperatingUnit::affiliatedWithLegalEntity($entityKey)->where('public_id', $id)->firstOrFail()
Read a unit key within a legal entityOrganizationDirectory::operatingUnitKeyForLegalEntityPublicId($entityKey, $id)OperatingUnit::affiliatedWithLegalEntity($entityKey)->where('public_id', $id)->value('key')
Read the public ID for a keyOrganizationDirectory::operatingUnitPublicIdByKey($key)OperatingUnit::whereKey($key)->value('public_id')
Read a key from the public IDOrganizationDirectory::operatingUnitKeyByPublicId($id)OperatingUnit::where('public_id', $id)->value('key')
Read public IDs by keyOrganizationDirectory::operatingUnitPublicIdsByKeys($keys)OperatingUnit::whereKey($keys)->pluck('public_id', 'key')->all()
Find by keyOrganizationDirectory::findOperatingUnitByKey($key)OperatingUnit::find($key)
Find by several keysOrganizationDirectory::findOperatingUnitsByKeys($keys)OperatingUnit::whereKey($keys)->get()->all()
Require a key matchOrganizationDirectory::requireOperatingUnitByKey($key)OperatingUnit::findOrFail($key)
Show whether a unit is affiliatedOrganizationDirectory::isOperatingUnitAffiliatedWithLegalEntity($key, $entityKey)OperatingUnit::affiliatedWithLegalEntity($entityKey)->whereKey($key)->exists()
Validate current affiliation before a writeOrganizationDirectory::isOperatingUnitAffiliatedWithLegalEntity($key, $entityKey)Existing method. Use the host decision for that unit and legal entity.
List affiliated unit keys in the directoryOrganizationDirectory::operatingUnitKeysForLegalEntity($entityKey)OperatingUnit::affiliatedWithLegalEntity($entityKey)->pluck('key')->all()
Read the complete current affiliation keysOrganizationDirectory::operatingUnitKeysForLegalEntity($entityKey)Existing method. The host list is independent of snapshot contents.
List units effective on a dateOrganizationDirectory::effectiveOperatingUnitsForLegalEntity($entityKey, $asOf)OperatingUnit::forLegalEntity($entityKey, $asOf)->orderBy('display_label')->get()->all() Checks effectiveness on the given date. The affiliation scope checks affiliation.

Contracts still used for this feature

ContractExisting methods
OperatingUnitEvidenceDirectoryfindByKey(), effectiveForLegalEntity(), lockForLegalEntity()
OrganizationWritePreconditionsregister()
PersonOperatingUnitMembershipsmove()

Sites

TaskPrevious APIAPI to use
Display a site by keySiteDirectory::findForLegalEntity($siteKey, $entityKey, $asOf)Site::forLegalEntity($entityKey, $asOf)->find($siteKey)
Read an address or a SiteView by keySiteDirectory::findForLegalEntity($siteKey, $entityKey, $asOf)Existing method. The directory model returns null for address.
Display a site by public IDSiteDirectory::findByPublicIdForLegalEntity($id, $entityKey, $asOf)Site::forLegalEntity($entityKey, $asOf)->where('public_id', $id)->first()
Validate a site for a write or read its address by public IDSiteDirectory::findByPublicIdForLegalEntity($id, $entityKey, $asOf)Existing method. Use the exact current host lookup.
Display a site option listSiteDirectory::optionsForLegalEntity($entityKey, $asOf, $search, $limit)Site::forLegalEntity($entityKey, $asOf) See the search example below.
List site options with addresses or SiteView objectsSiteDirectory::optionsForLegalEntity($entityKey, $asOf, $search, $limit)Existing method. The host returns the full option objects.

For a label or code search, use the current input $search and the usual 1–100 option limit.

Code example
PHP
use Nexia\Laravel\Directory\Site;

$search = trim($search);
$term = '%'.addcslashes($search, '\\%_').'%';

$sites = Site::forLegalEntity($entityKey, $asOf)
    ->when($search !== '', fn ($query) => $query->where(
        fn ($fields) => $fields->where('label', 'ilike', $term)
            ->orWhere('code', 'ilike', $term),
    ))
    ->orderBy('label')
    ->limit(max(1, min($limit, 100)))
    ->get();

The Site model returns address = null. In developer-local mode the Site scope checks current Core eligibility before reading the snapshot. Refresh the snapshot to see newly added sites and updated labels. Use $user->actor(), $entity->context() or $unit->context() when an already-loaded row needs its platform object. These may return null.

Approval

Query approval lists and details

In an authenticated App request, pass the selected legal entity to the SDK query.

Code example
PHP
use Nexia\Approval\Approval;

$page = Approval::query($legalEntity)->orderByDesc('submitted_at')->paginate(25);
$first = Approval::query($legalEntity)->orderByDesc('submitted_at')->first();
$approval = Approval::query($legalEntity)->find($approvalPublicId);

Use throughResource() for a filter published by the App that owns the linked record. Keep caseSummary() for workflows that reconcile an App record against an approval outcome. Those workflows may need evidence from an administratively removed case, and verified event handlers can use that contract.

TaskPrevious APIAPI to use
Display an approval listNo dedicated SDK list queryApproval::query($legalEntity)->paginate(25)
Display the first matching approvalNo dedicated SDK filter queryApproval::query($legalEntity)->first()
Display one native approvalApprovalHost::caseSummary($caseId)Approval::query($legalEntity)->where('source', 'native')->find($caseId)
Reconcile an approval outcome or process a verified eventApprovalHost::caseSummary($caseId)Existing method. Binding and resource versions and automatic-decision evidence come from the host summary.
Resolve the applicable routeApprovalHost::resolveRoute($routePolicyKey, $entity)Keep the existing method Resolve the applicable approval route.
Check whether an active route appliesApprovalHost::routeExists($routePolicyKey, $legalEntityId)Keep the existing method Check whether an applicable active route exists.
Render a previewApprovalHost::renderDocument($resourceKey, $values)Keep the existing method Render the document preview.
Prepare attachment evidenceApprovalHost::prepareSupportingAttachments($entity, $drafter, $stageIds)Keep the existing method Prepare submission attachment evidence.
Resolve the approver lineApprovalHost::resolveRouteLine($routeId, $routeKey, $routeVersion, $entity, $submitter, $resourceRef, $payload)Keep the existing method Resolve the line for the submission.
Submit using a specified bindingApprovalHost::submitBound($submission, $attachments)Keep the existing method Submit with the specified binding.
Submit using the current published versionsApprovalHost::submitCurrentBound($submission, $attachments)Keep the existing method Snapshot the current published versions and submit.
Recall an approvalApprovalHost::recall($caseId, $actor)Keep the existing method Recall the approval.

Contracts still used for this feature

ContractExisting methods
ApprovalBindingDirectoryavailabilityFor()
ApprovalRequirementsrequired()
ApprovalSubmissionHostenqueueBound(), delivery()
ApprovalIdempotencyexecute()
ApprovalLineResolverresolve()
ApprovalRequirementContextProviderapprovalRequirementContexts()
ApprovalResolverRegistrarregister(), registered()
AutomaticApprovalFactProviderevaluate()
AutomaticApprovalFactProviderRegistrarregister(), registered()
ResourceSubjectActorsubjectActorKey()
ResourceSubjectActorRegistrarregister(), registered()
ApprovalTestHostcreateCase(), caseCount(), case(), resetContributions(), registerBinding(), registerDocumentSchema(), createFixedUserRoute(), publishBusinessTemplate(), approve()

Person profiles

TaskPrevious APIAPI to use
Read one person profilePersonProfileDirectory::findByPartyKey()Existing method
Read profiles in a batchBatchPersonProfileDirectory::findByPartyKeys()Existing method when the host supports profile batches

Contracts still used for this feature

ContractExisting methods
PersonProfileEditorupdateForAuthorizedHr(), updateOwnContact()
PersonProfileHistorypageForAuthorizedHr()

Model attributes

For directory display use getKey(), public_id and display_label for key(), publicId() and displayLabel().

  • Actor — partyKey() → party_key, isVerified() → verified
  • Party — isPerson() → person, isOrganization() → organization, isArchived() → archived
  • LegalEntity — code() → code, partyPublicId() → party_public_id, isActiveOrganization() → active
  • OperatingUnit — code() → code, parentKey() → parent_key, classification() → classification, accentColor() → accent_color
Source of truth: docs/developers/content/en/building-apps/sdk-query-migration.md