API to create a new user

[franck-boullier]

How it should work:

Input:

• requestorAPIKey: the MEFE API Key of the user requesting the creation of the new user.
• Information about the user to be created:
  • Unique ID of the user in the source system: the system where the user information is coming from (if empty we user the email address)
  • System where this information is stored (if empty, we use the default table configured when the UNTE master account was created)
  • Table in the system where this information is stored (if empty, we use the default table configured when the UNTE master account was created)
  • email address
  • Given Name
  • Middle Name
  • Family Name
  • Salutation (Mr, Mrs, Dr, etc...)
  • Alias
  • Gender
  • Job Title
  • Organization
  • Phone Number 1
  • Phone Number 2
  • country: the 2 letter ISO code for the country example: SG or AU
  • Area: One of the Unee-T Enterprise Areas available from the Unee-T Enterprise interface.
  • Unee-T User Type: One of the Unee-T user types available from the Unee-T Enterprise Interface
  • MEFE API key for the user who supervises this new user.

Output:

Success:

Returns:

• MEFE API Key associated to this users and user creator.

Keep in mind that the same user can be associated to several different API keys giving him/her access to different units.

Example:

Step 1

A user user@example.com is created in Unee-T by a user enterprise_A@example.com.

The user enterprise_A@example.com will need to grant access to several units in his organization:

• Unit 1-A
• Unit 2-A

The user user@example.com has:

• 1 unique MEFE user id mefe_unique_user_id
• 1 unique MEFE API key apikey_A that grants him/her accesses and permissions to Unit 1-A and Unit 2-A

User enterprise_A@example.com can only see the API key apikey_A associated to user@example.com. User enterprise_A@example.com can use the API key apikey_A to allow access to Unee-T via a 3rd party app created by Enterpirse A.

Step 2

Another user enterprise_B@example.com "creates" the same user user@example.com in Unee-T.

The user enterprise_B@example.com will need to grant access to several units in his organization:

• Unit 1-B
• Unit 2-B

The user user@example.com has:

• 1 unique MEFE user id mefe_unique_user_id
• 1 unique MEFE API key apikey_B that grants him/her accesses and permissions to Unit 1-B and Unit 2-B

User enterprise_B@example.com can only see the API key apikey_B associated to user@example.com. User enterprise_B@example.com can use the API key apikey_B to allow access to Unee-T via a 3rd party app created by Enterpirse B.

Failure:

Include descriptive error message.

What happens in the back end:

• Unee-T Enterprise checks if user creator_id is allowed to create a new user.
• Unee-T Enterprise uses the MEFE API to create a new user to create the new user

[kaihendry]

wrt returns for #2, #3, #4, #5, #6, #7, we cannot respond whether the set data has been successfully invoked/setup on MEFE et al.

We can respond basically that the data has been written to the table successfully or not. That's it.

As for responding with "MEFE API Key associated to this users and user creator." or "Return timestamp: date and time (Z) when the user was successfully added to the unit.", we can't do that.

Another "check my request API" needs to be documented, where the client has to poll to work out how their set data has been applied. That "check my request API" is how @franck-boullier currently checks his relevant (logging) tables to know whether our asynchronous jobs were successful or not, or yet to be run.

[kaihendry]

for e.g. next steps here is how to query that given that a new user has been created in the relevant table (what table is this btw?), demonstrate how to find "MEFE API Key associated to this users and user creator.". I.e. what is the SQL query to know that this new user has been created.

[franck-boullier]

How the user creation works in UNTE:

UNTE master user insert the user information about user that needs to be created. As part of this process we will have the following information:

• external_person_id: the Unique ID of the user in the source system: the system where the user information is coming from (if empty, we use the email address for the user).
• external_system: System where this information is stored (if empty, we use the default table configured when the UNTE master account was created)
• table_in_external_system: Table in the system where this information is stored (if empty, we use the default table configured when the UNTE master account was created)
• organization_id: a unique ID attached to the API key for the Master user for the UNTE enterprise account

After the user creation request is sent to the UNTE:

In the UNTE database the tables that matter is the table ut_map_external_source_users The query you need is

SELECT 
  `unee_t_mefe_user_id`
  , `unee_t_mefe_user_api_key`
  , `uneet_created_datetime`
  , `is_mefe_api_success`
  , `mefe_api_error_message`
FROM `ut_map_external_source_users`
WHERE `external_person_id` = "[external_person_id]"
  AND `external_system` = "[external_system]"
  AND `table_in_external_system` = "[table_in_external_system]"
  AND `organization_id` = "[organization_id]"
;

This will return a single record where:

• unee_t_mefe_user_id is a STRING: The MEFE user ID for this user (probably not needed though)
• unee_t_mefe_user_api_key is a STRING: the API key for this user.
• uneet_created_datetime is a TIMESTAMP (Z) the date and time when the user was created
• is_mefe_api_success is either 1 (TRUE) or 0 (FALSE)
• mefe_api_error_message is a STRING: the error message we received if any

[kaihendry]

Is organization_id the same as organization_key or is it different?

I'm not clear what table the created user data goes into. persons or external_persons ? table_in_external_system is not in the persons table for e.g.

I don't quite understand "After the user creation request is sent to the UNTE". Is that to give info on the request like https://github.com/unee-t/enterprise-rest-api/issues/10 ?