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):

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:

RemoveRoleFromActorModelUpdat:

Actor properties

ChangePersonFieldsetUpdate:

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

ChangeOrganizationFieldsetUpdate:

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

ChangeResourceFieldsetUpdate:

ChangePaymentInfoModelUpdate :

SetUserReferenceModelUpdate:

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:

ChangePreferredCommunicationUpdate :

ChangeGenderModelUpdate:

RemoveGenderModelUpdate:

SetAvatarModelUpdate:

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

Address management

AddAddressModelUpdate:

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:

RemoveAddressModelUpdate :

Email management

AddEmailUpdate :

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

ChangeEmailUpdate :

RemoveEmailsUpdate :

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

RemoveEmailsUpdate :

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

Phone management

AddPhoneModelUpdate:

The phone number is not validated on the server side.

ChangePhoneModelUpdate:

RemovePhoneModelUpdate :

Web address management

AddWebAddressModelUpdate:

The web address is not validated on the server side.

ChangeWebAddressModelUpdate :

RemoveWebAddressModelUpdate :

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:

Example #2:

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:

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

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

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.