Skip to main content

Model Updates

Model updates are used to modify actor properties dynamically, allowing for efficient role management and attribute customization. These updates can be used to assign or remove roles and update personal information such as names, birthdates, and social security numbers. Below is a breakdown of the available model updates for managing actors in the system.

Roles Management​

Roles define the permissions and classifications assigned to an actor. The following model updates allow for role modification:

AddRoleToActorModelUpdate​

Adds a specified role to an actor.

interface IAddRoleToActorModelUpdate {
    roleId: number;
}

RemoveRoleFromActorModelUpdate​

Removes a specified role from an actor.

interface IRemoveRoleFromActorModelUpdate {
    roleId: number;
}

Actor Properties Management​

This section defines updates that modify an actor’s core attributes, such as personal information and status.

ChangePersonFieldsetUpdate​

This model update is used to modify the most relevant personal details of an actor.

interface IChangePersonFieldsetUpdate {
    birthDateUtc?: IOptional<Date|null>;
    deathDateUtc?: IOptional<Date|null>;
    firstName?: IOptional<string>;
    genderCode?: IOptional<GenderCode|null>;
    lastName?: IOptional<string>;
    maritalStatus?: IOptional<MaritalStatus|null>;
    middleName?: IOptional<string>;
    nationalityId?: IOptional<number|null>;
    occupation?: IOptional<string>;
    personState?: IOptional<PersonState|null>;
    ssn?: IOptional<string>;
}

enum GenderCode {
    Male = 1,
    Female = 2
}

ChangeOrganizationFieldsetUpdate​

This model update allows modification of key organizational details.

interface IChangeOrganizationFieldsetUpdate {
    dissolvedDateUtc?: IOptional<Date|null>;
    establishedDateUtc?: IOptional<Date|null>;
    legalClassificationCode?: IOptional<string>;
    organizationalIdentifier?: IOptional<string>;
    organizationalUnitIdentifier?: IOptional<string>;
    organizationName?: IOptional<string>;
    organizationState?: IOptional<OrganizationState>;
    vatTaxRegistrationIdentifier?: IOptional<string>;
}

ChangeResourceFieldsetUpdate​

interface IChangeResourceFieldsetUpdate {
    description?: IOptional<string>;
    name?: IOptional<string>;
}

ChangePaymentInfoModelUpdate​

This model update is used to update an actor’s financial and payment details.

interface IChangePaymentInfoModelUpdate {
    bankAccountNumber?: IOptional<string>;
    bankClearingNumber?: IOptional<string>;
    bankIdentifierCode?: IOptional<string>;
    bankName?: IOptional<string>;
    fikCode?: IOptional<number>;
    fikCreditorNumber?: IOptional<string>;
    fikIdentificationNumber?: IOptional<string>;
    internationalBankAccountNumber?: IOptional<string>;
    mobilePay?: IOptional<string>;
}

SetUserReferenceModelUpdate​

This model update links an actor to a security user.

interface ISetUserReferenceModelUpdate {
    displayName: string;
    userId: number;
}
Important Note

Do not use SetUserReferenceModelUpdate and the 'User' role at the same time. This model update will override any user created by the 'User' role.

RemoveUserReferenceModelUpdate​

interface IRemoveUserReferenceModelUpdate {}

ChangePreferredCommunicationUpdate​

interface IChangePreferredCommunicationUpdate {
    isConsentReceived?: IOptional<boolean>;
    preferredCommunicationKind?: IOptional<PreferredCommunicationKind>;
}

ChangeGenderModelUpdate​

interface IChangeGenderModelUpdate {
    gender: Gender;
}

enum Gender {
    Male = 1,
    Female = 2
}

RemoveGenderModelUpdate​

interface IRemoveGenderModelUpdate {}

SetAvatarModelUpdate​

This model update assigns an avatar image to an actor.

interface ISetAvatarModelUpdate {
    avatarImageId: number;
}
Note

The avatarImageId corresponds to a media item. You can use MediaItemApiService to upload an image and retrieve its ID.

Address Management​

AddAddressModelUpdate​

This model update adds a new address to an actor.

export interface IAddAddressModelUpdate {
    addressLine1: string;
    addressLine2?: IOptional<string>;
    addressTypeId: number;
    country?: IOptional<string>;
    latitude?: IOptional<number|null>;
    longitude?: IOptional<number|null>;
    postalCode: string;
    postalDistrict?: IOptional<string>;
}
Note

The addressTypeId should correspond to an existing address type. You can retrieve available address types using the API call:

/api/actors/ActorAddressType/GetActorAddressTypes

ChangeAddressModelUpdate​

This model update modifies an existing address.

export interface IChangeAddressModelUpdate {
    addressLine1?: IOptional<string>;
    addressLine2?: IOptional<string>;
    addressTypeId: number;
    country?: IOptional<string>;
    latitude?: IOptional<number|null>;
    longitude?: IOptional<number|null>;
    postalCode?: IOptional<string>;
    postalDistrict?: IOptional<string>;
}

RemoveAddressModelUpdate​

Removes an existing address from an actor.

interface IRemoveAddressModelUpdate {
    addressId: number;
}

Email Management​

AddEmailUpdate​

Defines the structure for adding a new email address, including an option to designate it as primary or secondary.

interface IAddEmailUpdate {
    address: string;
    isInvoice?: IOptional<boolean>;
    makePrimary: boolean;
}

There are two types of emails: primary and secondary, controlled by the makePrimary property.

ChangeEmailUpdate​

Provides functionality to modify an existing email address, with optional updates to its primary designation.

interface IChangeEmailUpdate {
    address?: IOptional<string>;
    emailId: number;
    makePrimary?: IOptional<boolean>;
}

RemoveEmailsUpdate​

Specifies the structure for removing multiple email addresses by their unique identifiers.

interface IRemoveEmailsUpdate {
    emailIds: number[];
}

Phone Management​

AddPhoneModelUpdate​

Defines the structure for adding a new phone number, categorizing it as either Home or Office.

interface IAddPhoneModelUpdate {
    phoneKind: PhoneKind;
    phoneNumber: string;
}

enum PhoneKind {
    Home = 1,
    Office = 2
}

The phone number is not validated on the server side.

ChangePhoneModelUpdate​

Enables modifications to an existing phone number, including its type and value.

interface IChangePhoneModelUpdate {
    actorPhoneId: number;
    phoneKind?: IOptional<PhoneKind>;
    phoneNumber?: IOptional<string>;
}

RemovePhoneModelUpdate​

Specifies the format for deleting a phone number by its unique identifier.

interface IRemovePhoneModelUpdate {
    actorPhoneId: number;
}

Web Address Management​

AddWebAddressModelUpdate​

Defines the structure for adding a web address and classifying it as either primary or secondary.

interface IAddWebAddressModelUpdate {
    address: string;
    kind: WebAddressKind;
}

enum WebAddressKind {
    Primary = 1,
    Secondary = 2
}

The web address is not validated on the server side.

ChangeWebAddressModelUpdate​

Provides the ability to update an existing web address, including modifications to its properties.

interface IChangeWebAddressModelUpdate {
    address?: IOptional<string>;
    webAddressId: number;
}

RemoveWebAddressModelUpdate​

Specifies the format for deleting a web address by its unique identifier.

interface IRemoveWebAddressModelUpdate {
    webAddressId: number;
}

Custom (EAV) Field Model Updates​

You can add custom information to any actor through EAV Fields (Custom Fields). Before adding information to an actor, you must first create the custom field. See ActorCustomFieldApiService.

Supported field types: boolean, date time, decimal, int, memo, options, string, url, catalog.

To add information to an actor, use Set{FieldType}EavValueModelUpdate, where {FieldType} corresponds to one of the supported types.

Management of EAV field values is described in detail in EAV Fields.

Change Actor Role Flow​

There are cases where a user needs to transition from one role to another. For example, a Person may need to be converted to an Organization, or a CustomerPerson to a CustomerOrganization.

To accomplish this, an UpdateActorCommand should be composed with one or more RemoveRoleFromActorModelUpdate instances to remove the current role and its related roles, and one or more AddRoleToActorModelUpdate instances to add the required roles.

Example: Changing CustomerPerson to CustomerOrganization​

To transition a CustomerPerson to a CustomerOrganization, the following roles should be removed:

  • Person
  • CustomerPerson

And the following roles should be added:

  • Organization
  • CustomerOrganization

Additionally, it is advisable to populate the necessary fields in the Organizational fieldset using ChangeOrganizationFieldsetUpdate.

Example: Changing CustomerOrganization to CustomerPerson​

To transition a CustomerOrganization to a CustomerPerson, the following roles should be removed:

  • Organization
  • CustomerOrganization

And the following roles should be added:

  • Person
  • CustomerPerson

Afterward, the Person fieldset fields should be updated using ChangePersonFieldsetUpdate.

Last updated on