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 doing | Use |
|---|---|
| Read, filter or join directory rows | Party::query(), User::query(), LegalEntity::query(), OperatingUnit::query() or Site::query() |
| Read approvals for the current user | Approval::query($legalEntity) with paginate(), first() or find() |
| Check access or current eligibility, submit an approval, or reconcile an outcome | The 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
| Task | Previous API | API to use |
|---|---|---|
| Find by public ID | PartyDirectory::findByPublicId($id) | Party::where('public_id', $id)->first() |
| Require a public-ID match | PartyDirectory::requireByPublicId($id) | Party::where('public_id', $id)->firstOrFail() |
| Check whether a public ID exists | PartyDirectory::exists($id) | Party::where('public_id', $id)->exists() For access decisions, use PartyAccess::allows(). |
| Find several public IDs | PartyDirectory::findByPublicIds($ids) | Party::whereIn('public_id', $ids)->get()->keyBy('public_id')->all() Keeps the public-ID map. Values are Eloquent models. |
| Find by key | PartyDirectory::findByKey($key) | Party::find($key) |
| Find by several keys | PartyDirectory::findByKeys($keys) | Party::whereKey($keys)->get()->all() |
| Require a key match | PartyDirectory::requireByKey($key) | Party::findOrFail($key) |
| Read the public ID for a key | PartyDirectory::publicIdByKey($key) | Party::whereKey($key)->value('public_id') |
| Read public IDs by key | PartyDirectory::publicIdsByKeys($keys) | Party::whereKey($keys)->pluck('public_id', 'key')->all() |
| Resolve the surviving Party after a merge | PartyDirectory::findCanonicalByPublicId($id) | Party::canonical($id) Uses the host to follow merges. Returns a model with basic fields. |
| Search active Party names | PartyDirectory::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 visibility | PartyDirectory::activeSearch($search, $limit) | Existing method |
| Look up an active person by email | PartyDirectory::activePeopleByEmail($email, $limit) | Party::peopleByEmail($email, $limit) Uses the same host lookup and returns a collection of models. |
| Search for people, including by email | PartyDirectory::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 name | PartyDirectory::orderByDisplayLabel($builder, $partyKeyColumn, $direction) | leftJoinSub() Join Party and order by display_name. |
| Sort App rows with caller visibility or across connections | PartyDirectory::orderByDisplayLabel($builder, $partyKeyColumn, $direction) | Existing method |
| Filter App rows by Party name | PartyDirectory::whereDisplayLabelMatches($builder, $partyKeyColumn, $search) | whereIn($partyKeyColumn, Party::matchingName($search)->select('key')) |
| Filter App rows with caller visibility or across connections | PartyDirectory::whereDisplayLabelMatches($builder, $partyKeyColumn, $search) | Existing method |
| Resolve merged Parties in a batch | BatchCanonicalPartyDirectory::findCanonicalByPublicIds($ids) | Party::canonicalMany($ids) Uses batch lookup when available and individual lookups otherwise. Returns a model collection. |
| Look up people by multiple emails | BatchPartyDirectory::activePeopleByEmails($emails, $limitPerEmail) | Party::peopleByEmails($emails, $limitPerEmail) Returns model collections keyed by normalized email. Requires the batch host contract. |
| Read roles by Party | PartyBusinessDirectory::activeRoles($actor, $ids) | Party::roles($actor, $ids) The public-ID map becomes a collection. |
| Search Parties by role and type | PartyBusinessDirectory::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 Party | PartyBusinessDirectory::activeRelationships($actor, $ids) | Party::relationships($actor, $ids) The public-ID map becomes a collection. |
| Read one visible relationship | PartyRelationshipDirectory::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 Party | PartyAccess::allows($actor, $partyKey) | Keep the existing method Keep for a caller-specific access decision. |
Contracts still used for this feature
| Contract | Existing methods |
|---|---|
PartyWritePreconditions | register() |
PersonPartyProvisioner | ensureForDirectorySubject() |
User accounts
| Task | Previous API | API to use |
|---|---|---|
| Find by key, including deleted accounts if requested | ActorDirectory::findByKey($key, $includeDeleted) | $key === null ? null : User::withTrashed($includeDeleted)->find($key) |
| Find by several keys | ActorDirectory::findByKeys($keys, $includeDeleted) | User::withTrashed($includeDeleted)->whereKey($keys)->get()->all() |
| Require a key match | ActorDirectory::requireByKey($key, $includeDeleted) | User::withTrashed($includeDeleted)->findOrFail($key) |
| Find by public ID | ActorDirectory::findByPublicId($id) | User::where('public_id', $id)->first() |
| Require a public-ID match | ActorDirectory::requireByPublicId($id) | User::where('public_id', $id)->firstOrFail() |
| Find the first account for a Party | ActorDirectory::findByPartyKey($partyKey) | User::where('party_key', $partyKey)->orderBy('key')->first() Ascending key preserves the first-account selection. |
| Read a key from the public ID | ActorDirectory::keyByPublicId($id) | User::where('public_id', $id)->value('key') |
| Read a public ID by key | ActorDirectory::publicIdByKey($key) | User::whereKey($key)->value('public_id') |
| Read public IDs by key | ActorDirectory::publicIdsByKeys($keys) | User::whereKey($keys)->pluck('public_id', 'key')->all() |
| Read the display label | ActorDirectory::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 exists | ActorDirectory::existsByKey($key, $includeDeleted) | User::withTrashed($includeDeleted)->whereKey($key)->exists() |
| Find accounts by public IDs | BatchActorDirectory::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 entity | ActorDirectory::activeByPublicIdForLegalEntity($id, $entityKey) | User::activeForLegalEntity($entityKey)->where('public_id', $id)->first() |
| Verify current eligibility for a specific account | ActorDirectory::activeByPublicIdForLegalEntity($id, $entityKey) | Existing method. Get the live single-account decision and Actor. |
| List active accounts in a legal entity | ActorDirectory::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
| Contract | Existing methods |
|---|---|
PersonLoginAccounts | ensure() |
PersonLoginInvitations | status(), invite() |
BatchPersonLoginInvitations | statuses() |
Legal entities
| Task | Previous API | API to use |
|---|---|---|
| Find by public ID | OrganizationDirectory::findLegalEntity($id) | LegalEntity::where('public_id', $id)->first() |
| Require a public-ID match | OrganizationDirectory::legalEntity($id) | LegalEntity::where('public_id', $id)->firstOrFail() |
| Find an active entity by public ID | OrganizationDirectory::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 key | OrganizationDirectory::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 key | OrganizationDirectory::findLegalEntityByKey($key) | LegalEntity::find($key) |
| Find by several keys | OrganizationDirectory::findLegalEntitiesByKeys($keys) | LegalEntity::whereKey($keys)->get()->all() |
| Require a key match | OrganizationDirectory::requireLegalEntityByKey($key) | LegalEntity::findOrFail($key) |
| Read the public ID for a key | OrganizationDirectory::legalEntityPublicIdByKey($key) | LegalEntity::whereKey($key)->value('public_id') |
| Read a key from the public ID | OrganizationDirectory::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 key | OrganizationDirectory::legalEntityPublicIdsByKeys($keys) | LegalEntity::whereKey($keys)->pluck('public_id', 'key')->all() |
| Read a hierarchy revision | OrganizationDirectory::legalEntityHierarchyRevisionByKey($key) | $entity->hierarchyRevision() On an already-loaded model. Calls the existing host method. Core and Manager currently return null. |
| List legal entities | OrganizationDirectory::legalEntities() | LegalEntity::orderBy('code')->get()->all() Keep the authorized target resolver for selectable entities. |
Contracts still used for this feature
| Contract | Existing methods |
|---|---|
HasLegalEntityProfile | legalProfile() |
HasFunctionalCurrency | functionalCurrencyCode(), functionalCurrencyMinorUnit() |
OrganizationMemberships | actorParticipatesInLegalEntity() |
OrganizationTargetResolver | resolveListTargets(), resolveCreateTarget() |
PersonLegalEntityAccess | end() |
Operating units
| Task | Previous API | API to use |
|---|---|---|
| Find by public ID | OrganizationDirectory::findOperatingUnit($id) | OperatingUnit::where('public_id', $id)->first() |
| Require a unit affiliated with a legal entity | OrganizationDirectory::operatingUnit($id, $entityKey) | OperatingUnit::affiliatedWithLegalEntity($entityKey)->where('public_id', $id)->firstOrFail() |
| Read a unit key within a legal entity | OrganizationDirectory::operatingUnitKeyForLegalEntityPublicId($entityKey, $id) | OperatingUnit::affiliatedWithLegalEntity($entityKey)->where('public_id', $id)->value('key') |
| Read the public ID for a key | OrganizationDirectory::operatingUnitPublicIdByKey($key) | OperatingUnit::whereKey($key)->value('public_id') |
| Read a key from the public ID | OrganizationDirectory::operatingUnitKeyByPublicId($id) | OperatingUnit::where('public_id', $id)->value('key') |
| Read public IDs by key | OrganizationDirectory::operatingUnitPublicIdsByKeys($keys) | OperatingUnit::whereKey($keys)->pluck('public_id', 'key')->all() |
| Find by key | OrganizationDirectory::findOperatingUnitByKey($key) | OperatingUnit::find($key) |
| Find by several keys | OrganizationDirectory::findOperatingUnitsByKeys($keys) | OperatingUnit::whereKey($keys)->get()->all() |
| Require a key match | OrganizationDirectory::requireOperatingUnitByKey($key) | OperatingUnit::findOrFail($key) |
| Show whether a unit is affiliated | OrganizationDirectory::isOperatingUnitAffiliatedWithLegalEntity($key, $entityKey) | OperatingUnit::affiliatedWithLegalEntity($entityKey)->whereKey($key)->exists() |
| Validate current affiliation before a write | OrganizationDirectory::isOperatingUnitAffiliatedWithLegalEntity($key, $entityKey) | Existing method. Use the host decision for that unit and legal entity. |
| List affiliated unit keys in the directory | OrganizationDirectory::operatingUnitKeysForLegalEntity($entityKey) | OperatingUnit::affiliatedWithLegalEntity($entityKey)->pluck('key')->all() |
| Read the complete current affiliation keys | OrganizationDirectory::operatingUnitKeysForLegalEntity($entityKey) | Existing method. The host list is independent of snapshot contents. |
| List units effective on a date | OrganizationDirectory::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
| Contract | Existing methods |
|---|---|
OperatingUnitEvidenceDirectory | findByKey(), effectiveForLegalEntity(), lockForLegalEntity() |
OrganizationWritePreconditions | register() |
PersonOperatingUnitMemberships | move() |
Sites
| Task | Previous API | API to use |
|---|---|---|
| Display a site by key | SiteDirectory::findForLegalEntity($siteKey, $entityKey, $asOf) | Site::forLegalEntity($entityKey, $asOf)->find($siteKey) |
| Read an address or a SiteView by key | SiteDirectory::findForLegalEntity($siteKey, $entityKey, $asOf) | Existing method. The directory model returns null for address. |
| Display a site by public ID | SiteDirectory::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 ID | SiteDirectory::findByPublicIdForLegalEntity($id, $entityKey, $asOf) | Existing method. Use the exact current host lookup. |
| Display a site option list | SiteDirectory::optionsForLegalEntity($entityKey, $asOf, $search, $limit) | Site::forLegalEntity($entityKey, $asOf) See the search example below. |
| List site options with addresses or SiteView objects | SiteDirectory::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.
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.
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.
| Task | Previous API | API to use |
|---|---|---|
| Display an approval list | No dedicated SDK list query | Approval::query($legalEntity)->paginate(25) |
| Display the first matching approval | No dedicated SDK filter query | Approval::query($legalEntity)->first() |
| Display one native approval | ApprovalHost::caseSummary($caseId) | Approval::query($legalEntity)->where('source', 'native')->find($caseId) |
| Reconcile an approval outcome or process a verified event | ApprovalHost::caseSummary($caseId) | Existing method. Binding and resource versions and automatic-decision evidence come from the host summary. |
| Resolve the applicable route | ApprovalHost::resolveRoute($routePolicyKey, $entity) | Keep the existing method Resolve the applicable approval route. |
| Check whether an active route applies | ApprovalHost::routeExists($routePolicyKey, $legalEntityId) | Keep the existing method Check whether an applicable active route exists. |
| Render a preview | ApprovalHost::renderDocument($resourceKey, $values) | Keep the existing method Render the document preview. |
| Prepare attachment evidence | ApprovalHost::prepareSupportingAttachments($entity, $drafter, $stageIds) | Keep the existing method Prepare submission attachment evidence. |
| Resolve the approver line | ApprovalHost::resolveRouteLine($routeId, $routeKey, $routeVersion, $entity, $submitter, $resourceRef, $payload) | Keep the existing method Resolve the line for the submission. |
| Submit using a specified binding | ApprovalHost::submitBound($submission, $attachments) | Keep the existing method Submit with the specified binding. |
| Submit using the current published versions | ApprovalHost::submitCurrentBound($submission, $attachments) | Keep the existing method Snapshot the current published versions and submit. |
| Recall an approval | ApprovalHost::recall($caseId, $actor) | Keep the existing method Recall the approval. |
Contracts still used for this feature
| Contract | Existing methods |
|---|---|
ApprovalBindingDirectory | availabilityFor() |
ApprovalRequirements | required() |
ApprovalSubmissionHost | enqueueBound(), delivery() |
ApprovalIdempotency | execute() |
ApprovalLineResolver | resolve() |
ApprovalRequirementContextProvider | approvalRequirementContexts() |
ApprovalResolverRegistrar | register(), registered() |
AutomaticApprovalFactProvider | evaluate() |
AutomaticApprovalFactProviderRegistrar | register(), registered() |
ResourceSubjectActor | subjectActorKey() |
ResourceSubjectActorRegistrar | register(), registered() |
ApprovalTestHost | createCase(), caseCount(), case(), resetContributions(), registerBinding(), registerDocumentSchema(), createFixedUserRoute(), publishBusinessTemplate(), approve() |
Person profiles
| Task | Previous API | API to use |
|---|---|---|
| Read one person profile | PersonProfileDirectory::findByPartyKey() | Existing method |
| Read profiles in a batch | BatchPersonProfileDirectory::findByPartyKeys() | Existing method when the host supports profile batches |
Contracts still used for this feature
| Contract | Existing methods |
|---|---|
PersonProfileEditor | updateForAuthorizedHr(), updateOwnContact() |
PersonProfileHistory | pageForAuthorizedHr() |
Model attributes
For directory display use getKey(), public_id and display_label for key(), publicId() and displayLabel().
Actor—partyKey()→party_key,isVerified()→verifiedParty—isPerson()→person,isOrganization()→organization,isArchived()→archivedLegalEntity—code()→code,partyPublicId()→party_public_id,isActiveOrganization()→activeOperatingUnit—code()→code,parentKey()→parent_key,classification()→classification,accentColor()→accent_color