How to create/update Actor

This article contains information about how to create/update actor in CRS.

We have type safe proxies for C#, typescript (JS), Kotlin, swift - this guide is however aimed at developers who do not implement for native IOS, Android or typescript (e.g. php developers).

If you need access to our proxies please contact us.

1 Get actors(paged)
2 Get actor infos(paged)
3 Create Actor
4 Update Actor
5 Model updates
- 5.1 Roles
- 5.2 Actor properties
- 5.3 Address management
- 5.4 Email management
- 5.5 Phone management
- 5.6 Web address management
- 5.7 Custom(EAV) field model updates
- 5.8 Change actor role flow
6 Examples

Get actors(paged)

Word: POST
URL: {host_url}/api/actors/actor/GetActorsPage
Minimal request:

{ 
   "sortInfo":[
   ],
   "propertiesToLoad": <write flags value>,
   "offset":0,
   "count":page_size,
   "includeOverallEntryCount":true
}

[propertiesToLoad] - flag enumeration with same options that also used in GetActor call (see previous chapter).

Following optional filters are available and need to be mentioned:

[RoleSystemName]- allows to filter actors by specific role
[SearchPattern] - allows to filter actor which person or organization name, phone, email or customer identifier satisfies search pattern
[ModifiedAtFrom] - allows to filter actors modified after specific timestamp
[ModifiedAtTo] - allows to filter actors modified before specific timestamp

[ActorIds]- allows to filter actors by their ids

Get actor infos(paged)

Word: POST
URL: {host_url}/api/actors/actor/GetActorInfoPage
Minimal request:

{ 
   "offset":0,
   "count":page_size,
   "includeOverallEntryCount":true
}

Following optional filters are available and need to be mentioned:

[RoleSystemNames]- allows to filter actors by specific roles
[ActorIds]- allows to filter actors by their ids

Create Actor

Word: POST
URL: {host_url}/api/actors/Actor/CreateActor
Minimal Request(for create customer):

{
   "modelType":"CreateActorCommand",
   "modelUpdates":[
      {
         "modelType":"ChangePersonFieldsetUpdate",
         "firstName":{
            "value":"John"
         },
         "lastName":{
            "value":"Smoth"
         }
      }
   ],
   "roleNames":[
      "CustomerPerson",
      "Person",
      "Customer"
   ]
}

The roleIds field is an array of role ids, which will be assigned to the created actor (possible empty array).

To retrieve ids you can user RoleApiService:

getRoles() - gets list of roles, can be filtered by request parameters (include ids and exclude ids);
getRoleBySystemName() - gets role by System Name;

Notes: there is the hardcoded role System Name, which is equal to 'User'. This role controls do we need to create Security User or not. Eg. if you will add the 'User' role to new actor and send CreateActorCommand to the service, then server will automatically create new user. The new user will have Name = First Name + Last Name, the same E-Mail and Password = E-Mail.

The modelUpdate field will contain additional information, which will be filled to new actor (eg. First Name, Birthday, E-Mail and etc.). All model updates have the 'ModelUpdate' suffix. If any property has IOptional type, then this property is not required.

Model updates are the same for create and update actor cases and will be described in section below.

Update Actor

Word: POST
URL: {host_url}/api/actors/Actor/UpdateActor

Minimal Request(for create customer):

{
   "modelType":"UpdateActorCommand",
   "modelUpdates":[
      {
         "modelType":"ChangePersonFieldsetUpdate",
         "firstName":{
            "value":"John"
         },
         "lastName":{
            "value":"Smoth"
         }
      }
   ],
   "entityId":your_actor_id
}

In update actor command ActorId need to be specified in property entityId and also should be presented set of model updates in which should be defined which exactly properties need to be updated.

Model updates

Roles

AddRoleToActorModelUpdate:

interface IAddRoleToActorModelUpdate {
	roleId: number;
}

RemoveRoleFromActorModelUpdat:

interface IRemoveRoleFromActorModelUpdate {
	roleId: number;
}

Actor properties

ChangePersonFieldsetUpdate:

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
}

The main model update, which will fill the most useful information about actor (as person).

ChangeOrganizationFieldsetUpdate:

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>;
}

The main model update, which will fill the most useful information about actor (as organization).

ChangeResourceFieldsetUpdate:

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

ChangePaymentInfoModelUpdate :

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:

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

This model update is used to link Actor to Security User. To connect to specific user, you should set both properties userId and displayName (to values received from User entity). To get user information you can use UserApiService.

Warning: don't use this model update and the 'User' role at the same time. SetUserReferenceModelUpdate will always overwrite user create by '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:

interface ISetAvatarModelUpdate {
    avatarImageId: number;
}

The avatarImageId is ID of media item. To upload image and get ids you can user MediaItemApiService.

Address management

AddAddressModelUpdate:

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: addressTypeId should be Id of existing address type.

	To get all address types and decide what address to create please use api call /api/actors/ActorAddressType/GetActorAddressTypes

ChangeAddressModelUpdate:

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 :

interface IRemoveAddressModelUpdate {
	addressId: number;
}

Email management

AddEmailUpdate :

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

There are two types of E-Mail: primary and secondary, controlled by makePrimary property.

ChangeEmailUpdate :

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

RemoveEmailsUpdate :

interface IRemoveEmailsUpdate {
	emailIds: number[];
}

There are two types of E-Mail: primary and secondary, controlled by makePrimary property.

RemoveEmailsUpdate :

interface IRemoveEmailsUpdate {
	emailIds: number[];
}

There are two types of E-Mail: primary and secondary, controlled by makePrimary property.

Phone management

AddPhoneModelUpdate:

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

enum PhoneKind {
    Home = 1,
    Office = 2
}

The phone number is not validated on the server side.

ChangePhoneModelUpdate:

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

RemovePhoneModelUpdate :

interface IRemovePhoneModelUpdate {
	actorPhoneId: number;
}

Web address management

AddWebAddressModelUpdate:

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

enum WebAddressKind {
    Primary = 1,
    Secondary = 2
}

The web address is not validated on the server side.

ChangeWebAddressModelUpdate :

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

RemoveWebAddressModelUpdate :

interface IRemoveWebAddressModelUpdate {
	webAddressId: number;
}

Custom(EAV) field model updates

You can add custom information any actor through Eav Fields (Custom Fields). Before you can add information to actor, you should create the custom field. See ActorCustomFieldApiService.

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

To add information to actor you should use Set{FieldType}EavValueModelUpdate, where {FieldType} is one of supported types.

Management of EAV field values is described in following document : How to manage EAV fields

Change actor role flow

There is often case when user from one role need to be converted to other role. For example, may be a need to convert person to organization or customer person to customer organization.
To achieve that should be composed UpdateActorCommand with one or set of RemoveRoleFromActorModelUpdate instances to remove current role and its related roles and one or set of AddRoleToActorModelUpdate instances to add needed role and its related roles.

Common example is change CustomerPerson to CustomerOrganization and vice versa.

So to change CustomerPerson to CustomerOrganization it is needed to be removed roles Person, CustomerPerson and added roles Organization, CustomerOrganization.

Also it will be nice to fill necessary fields in Organizational fieldset using ChangeOrganizationFieldsetUpdate.

To change CustomerOrganization to CustomerPerson it is needed to be removed roles Organization, CustomerOrganization and added roles Person, CustomerPerson. Then PersonFieldset fields need to be changed using ChangePersonFieldsetUpdate

Examples

Example #1:

// This example will fetch ID of person role and then create new actor (set first name, last name, email, phone).
// You can separate these calls, for example, preload all required ids in initialization and then just pass it as array.
// Call role service to get role ids
this.roleApiService.getRoleBySystemName({ systemName: 'Person' })
    .then(responce => {
        let role = responce.errorOrValue.value.value;

        // Model Updates
        let personFieldset = new ChangePersonFieldsetUpdate();
        personFieldset.firstName = { value: 'Darth' };
        personFieldset.lastName = { value: 'Vader' };
        personFieldset.genderCode = { value: GenderCode.Male };

        let email = new AddEmailUpdate();
        email.address = 'darth.vader@galary.empire.gov';
        email.makePrimary = true;

        let phone = new AddPhoneModelUpdate();
        phone.phoneNumber = '+1 000 000 00 00'
        phone.phoneKind = PhoneKind.Office;

        // Create command with required information
        let command = new CreateActorCommand();
        command.modelUpdates = [personFieldset, email, phone];
        command.roleIds = [role.id];

        // Call actor service to create actor
        this.service.createActor(command).then(response => console.log('success'));
    });

Example #2:

// Create new custom field (type = string).
let command = new CreateEavFieldCommand();
command.displayName = 'Custom Field';
command.fieldTypeSystemName = 'String';
command.systemName = 'CustomField';
this.fieldApiService.createEavField(command)
    .then(r => {
        // save id to somewhere
        // let id = r.errorOrValue.value;

        console.log('success');
    })
    .catch(r => console.error('error'));

// --- some code ---

// Call role service to get role ids
this.roleApiService.getRoleBySystemName({ systemName: 'Person' })
    .then(response => {
        let role = response.errorOrValue.value.value;

        // Model Updates
        let personFieldset = new ChangePersonFieldsetUpdate();
        personFieldset.firstName = { value: 'Darth' };
        personFieldset.lastName = { value: 'Vader' };
        personFieldset.genderCode = { value: GenderCode.Male };

        let email = new AddEmailUpdate();
        email.address = 'darth.vader@galary.empire.gov';
        email.makePrimary = true;

        let phone = new AddPhoneModelUpdate();
        phone.phoneNumber = '+1 000 000 00 00'
        phone.phoneKind = PhoneKind.Office;

        let setField = new SetStringEavValueModelUpdate();
        setField.fieldSystemName = 'CustomField';
        setField.value = 'Value';

        // Create command with required information
        let command = new CreateActorCommand();
        command.modelUpdates = [personFieldset, email, phone, setField];
        command.roleIds = [role.id];

        // Call actor service to create actor
        this.service.createActor(command).then(response => console.log('success'));
    });

Example #3 - Convert customer person to customer organization and vice versa:

Step 1: Create Customer Person
URL: http://localhost:9000/api/actors/actor/createActor
Request Body:

{
   "modelType":"CreateActorCommand",
   "modelUpdates":[
      {
         "modelType":"AddEmailUpdate",
         "address":"test@gmail.com",
         "isInvoice":{
            "value":true
         }
      },
      {
         "modelType":"AddPhoneModelUpdate",
         "phoneNumber":"123456",
         "phoneKind":3
      },
      {
         "modelType":"ChangePersonFieldsetUpdate",
         "firstName":{
            "value":"a_person"
         },
         "lastName":{
            "value":"customer"
         }
      },
      {
         "modelType":"AddAddressModelUpdate",
         "addressTypeId":2,
         "addressLine1":"Aabakken 1",
         "addressLine2":{
            "value":"Rebæk"
         },
         "postalCode":"6000",
         "postalDistrict":{
            "value":"Kolding"
         }
      },
      {
         "modelType":"ChangePreferredCommunicationUpdate",
         "preferredCommunicationKind":{
            "value":0
         }
      }
   ],
   "roleNames":[
      "CustomerPerson",
      "Person",
      "Customer"
   ]
}

Step 2: Change from CustomerPerson to CustomerOrganisation
URL: http://localhost:9000/api/actors/actor/updateActor
Request Body:

{
   "modelUpdates":[
      {
         "modelType":"RemoveRoleFromActorModelUpdate",
         "roleId":8 --Customer Person role id
      },
      {
         "modelType":"RemoveRoleFromActorModelUpdate",
         "roleId":1 --Person role id
      },
      {
         "modelType":"AddRoleToActorModelUpdate",
         "roleId":9 -- Customer Organization role id
      },
      {
         "modelType":"AddRoleToActorModelUpdate",
         "roleId":2 -- Organization role id
      },
      {
         "modelType":"ChangeOrganizationFieldsetUpdate",
         "organizationName":{
            "value":"a_person"
         }
      },
      {
         "modelType":"ChangePersonFieldsetUpdate",
         "firstName":{
            "value":""
         },
         "lastName":{
            "value":""
         }
      }
   ],
   "modelType":"UpdateActorCommand",
   "entityId":11
}

Step 3: Change from CustomerOrganisation to CustomerPerson back
URL: http://localhost:9000/api/actors/actor/updateActor
Request Body:

{
   "modelUpdates":[
      {
         "modelType":"RemoveRoleFromActorModelUpdate",
         "roleId":9 -- Customer Organization role id
      },
      {
         "modelType":"RemoveRoleFromActorModelUpdate",
         "roleId":2 -- Organization role id
      },
      {
         "modelType":"AddRoleToActorModelUpdate",
         "roleId":8 --Customer Person role id
      },
      {
         "modelType":"AddRoleToActorModelUpdate",
         "roleId":1 --Person role id
      },
      {
         "modelType":"ChangePersonFieldsetUpdate",
         "firstName":{
            "value":"a_person"
         }
      },
      {
         "modelType":"ChangeOrganizationFieldsetUpdate",
         "organizationName":{
            "value":""
         }
      }
   ],
   "modelType":"UpdateActorCommand",
   "entityId":11
}

Note: Role Ids of Person, Customer etc. roles may be different in different tenants so should be used GetRoles method to resolve them by system names.

CRS public

How to create/update Actor

Get actors(paged)

Get actor infos(paged)

Create Actor

Update Actor

Model updates

Roles

Actor properties

Address management

Email management

Phone management

Web address management

Custom(EAV) field model updates

Change actor role flow

Examples

Example #1:

Example #2:

Example #3 - Convert customer person to customer organization and vice versa:

Related content