Folio Development Teams
Space shortcuts
Page tree
Skip to end of metadata
Go to start of metadata

MODCFIELDS-21 - Getting issue details... STATUS

The goal of the spike is to investigate how user data is imported and how the import process can be extended to include custom fields.

1) Import process in mod-user-import: 

mod-user-import receives a POST "/user-import" request with collection of all imported users in a body.

Schema for users in mod-import-user matches schema in mod-users.

Each user in collection is updated or created with POST /users or PUT /users/{id}. 

2) Adding custom fields to mod-user-import: 

To pass custom fields to mod-users we just need to add following property to import schema:

"customFields" : {
"description": "Object that contains custom field",
"type": "object",
"additionalProperties": true
}

3)Adjusting custom field definitions

There is a requirement that we need to adjust custom field definition before importing users. For example if imported users contain unknown option for drop-down field, we need to add this option to the list of allowed options.

Proposed approaches:

1) Get all custom field definitions for users from mod-users, then update definitions with PUT requests. The logic for updating custom field definition has to be added to UserImportAPI.

Advantages:

  • Logic related to user import will be stored in mod-user-import

Disadvantages: 

  • Import logic will be duplicated if later we need to import objects for other modules

2) Send flag "_extendDefinition" in POST /users and PUT /users/{id}. Flag "_extendDefinition" will change validation logic in mod-custom-fields.

If _extendDefinition is true then unknown options for select fields (single select dropdown, multi-select dropdown, radiobutton) will be added to custom field definition, instead of causing a validation error.

Example: 

Following request will add option "new department" to custom field "department_1"

POST /users
{
  ...
  "customFields": {
    "_extendDefinition": true,
    "department_1": "new department"
  }
}


Advantages:

  • Logic for processing "_extendDefinition" flag will be stored in mod-custom-fields, so it can be used in the future for importing objects to other modules.

Disadvantages:

  • It adds a special case and makes validation logic more complicated.

  • No labels

6 Comments

  1. Dmytro Tkachenko

    There is a requirement that we need to adjust custom field definition before importing users.

    As I remember there is a requirement not only to update an existing CF definition but also to add a new one (Khalilah Gambrell Is it true? ).

    Andrii Paias How the above can be supported?

    1. Andrii Paias

      If we will need to add new CF definitions, how will we determine the type of new custom field? We can accept the new CF definions as part of the request, but if user can provide such metadata then it is easier for user to just call POST /custom-fields before running import.

      If we have to deduce the type based on values then we can add this logic in both approaches. In first approach we will send appropriate POST requests from mod-user-import, in second approach we will add custom fields if "_extendDefinition" flag is present

      1. Dmytro Tkachenko

        If we will need to add new CF definitions, how will we determine the type of new custom field? We can accept the new CF definions as part of the request, but if user can provide such metadata then it is easier for user to just call POST /custom-fields before running import.

        I cannot tell exactly how, but if it's required we have to figure out how it can be achieved. Potentially yes some metadata would be required in request.

        Yes it would be easy to call  CF definition API beforehand but it'd require other tool (for importing CF definition). Don't know if it's acceptable to have 2 importing tools, one for user and another to CF definition, or everything should be done inside user importing

        1. Andrii Paias

          Thanks, if we will have CF definition then we will have to send them in POST/PUT /custom-fields requests from mod-import-user before running import

      2. Dmytro Tkachenko

        If we have to deduce the type based on values then we can add this logic in both approaches. In first approach we will send appropriate POST requests from mod-user-import, in second approach we will add custom fields if "_extendDefinition" flag is present

        If we recall "Single responsibility" principle then importing tool should be responsible for understanding input data and transforming it into the form acceptable by  other modules. Potentially the input format can be different from what is currently used by mod-users. It could include user data, CF values, CF definitions and other staff. The tool then translates the input into a set of appropriate API calls. In our case it would be calls to existing User API and CF definition API, they in turn also follow "Single responsibility" principle: User API updates data related to user only and do not modify anything outside of it, the same for CF definition API.

        So my point to not mix responsibilities between API implementations, in particular do not modify CF definitions inside user updates

  2. Dmytro Tkachenko

    2) Send flag "_extendDefinition" in POST /users and PUT /users/{id}. Flag "_extendDefinition" will change validation logic in mod-custom-fields.

    I don't really like the idea of mixing CF value updates with making changes in CF definition. Thus you'd couple different things together. We can discuss it but my initial impression that it is better to have these actions separated:

    • modification to CF definition is done from the importing tool by using standard CF definition API
    • CF values updated by User API as part of  user data import