Person pre creation process

Person pre creation process feature allows you to:

  • block person creation
  • update person's attributes during creation process
  • delete person's attributes during creation process

In order to be able to use this feature Extension needs to implement the PersonCreationPreProcessExtension. Person pre creation process is enabled by default and to disable it set environmental variable IDP_EXTENSION_PERSON_CREATION_PRE_PROCESS_ENABLED to false on the extension.

Pre processing extension point will receive following data:

  • expected_profile - profile of a person that is about to be created.
  • external_idp_attributes - all attributes coming from external identity provider that is used to create person.
  • identities - list of identities that will be created during person creation. This list in most cases will contain one element, but can also be empty in case external person id is unknown.
  • profile_candidates - list of existing CIM profiles that have been returned by person search preprocess extension

Pre processing extension point returns object with following fields:

  • person_creation_interrupted
  • prevent_person_creation_reason_code
  • update_profile_attributes
  • delete_profile_attributes
  • operation - action that should be taken after person creation pre-process, it can be set to CREATE or COUPLE. Defaults to CREATE.
  • profile_to_merge_with - nullable field that indicates to which profile should the new one be coupled to

Extension point usage

Person pre creation processing is executed when person is created:

  • via Person API
  • when inviting person
  • during person migration
  • during automatic sign-up

Blocking person creation

Person creation will be blocked in case person_creation_interrupted is true. Additionally if prevent_person_creation_reason_code is set person will receive custom error message (in API flow) or will be redirected back to login page where custom error will be displayed. Such custom message should have key defined in following format:

personal.person.pre.creation.error.custom.CODE where CODE is the value that is coming from extension when person creation is being blocked.

Those error messages can be specified in multiple languages. If user is created with preferred locale and error message with given code exists for that locale it will be used for that user in both API and web flows. Otherwise default locale will be chosen.

Updating person attributes

Person pre creation process allows you to modify or add person attributes before person is created. In order to update attributes provide new or updated values in update_profile_attributes. The only attribute that change will be ignored is the reference_id.

Providing following attributes

  • name
  • gender
  • date_of_birth
  • preferred_locale
  • migration_code
  • addresses

in update_profile_attributes will result in replacing old attribute properties with new ones.

Changing following attributes

  • custom_attributes
  • phone_numbers
  • email_addresses

will result in a merge with original values. Attributes with the same value identifier as in expected_profile, i.e.

  • name for custom attribute
  • value for email and phone number

will be updated, values with identifiers that were added to update_profile_attributes will also be added to person profile during person creation and identifiers that were provided in expected_profile and are missing in update_profile_attributes will not be removed.

Example. Custom attributes sent to PersonCreationPreProcessExtension:

"custom_attributes": [
  {
    "name": "keyA",
    "value": "valueA"
  },
  {
    "name": "keyB",
    "value": "valueB"
  }
]

Custom attributes sent in the extension's response in update_profile_attributes:

"custom_attributes": [
  {
    "name": "keyA",
    "value": "newValueA"
  },
  {
    "name": "keyC",
    "value": "valueC"
  }
]

Will result in saving 3 elements:

"custom_attributes": [
  {
    "name": "keyA",
    "value": "newValueA"
  },
  {
    "name": "keyB",
    "value": "valueB"
  },
  {
    "name": "keyC",
    "value": "valueC"
  }
]

Please note that merged profile has to respect current configuration. All mandatory fields have to be provided and all fields have to be consistent. In case merged profile validation fails (e.g. because of changing email that is already used by another person), person creation will still be blocked despite setting person_creation_interrupted to false.

Deleting person attributes

Currently, it is impossible to delete person attributes and values in delete_profile_attributes are ignored.

Determining action for profile candidates

When PersonCreationPreProcessSearchExtension is enabled all identities found by the query will end up in profile_candidates field. From now on there are two possible ways of handling such identities:

  1. Creating new account:

    If no account matches the PersonCreationPreProcess requirements you can set operation in PersonCreationPreProcessResponseDto to CREATE (or leave it blank as it is the default value). It will result in creating new profile.

  2. Coupling with existing account:

    If you wish to couple the new profile into existing one you have to set operation in PersonCreationPreProcessResponseDto to COUPLE and set the selected profile from profile_candidates to profile_to_merge_with field from response PersonCreationPreProcessResponseDto.