How it should work:

Input:

THIS NEEDS TO BE UPDATED IN LINE WITH WHAT WAS DISCUSSED IN #3

• requestorAPIKey: the MEFE API Key of the user requesting the change to the unit
• MEFE unit ID of the unit that needs to be modified
• The change that needs to be done:
  • name: a name for the unit (string)
  • type: The type of the unit. See the list of MEFE authorized unit type
  • moreInfo: Free text to add more information about the unit (excluding address information)
  • streetAddress: Street address and unit number if applicable
  • city: The city (a string)
  • state: regional subdivision or administrative region (ex: California)
  • zipCode: ZIP or Postal Code
  • country: the 2 letter ISO code for the country example: SG or AU
  • Parent Unit ID: the MEFE unit Id of the parent unit (ex: MEFE Unit Id of the building if the unit created is a flat or MEFE Unit Id of the flat if the unit created is a room

Output:

Success:

Return timestamp: date and time (Z) when the unit was successfully modified
The request ID for the update request

Failure:

Include descriptive error message.

What happens in the back end:

• Unee-T Enterprise checks if user requestorUserId is allowed to edit the unit.
• UNTE updates what needs to be updated
• UNTE uses the MEFE API to edit a unit.

One of the requirement of #3 is that the 3rd party uses a valid Unit Type when a unit is created or modified.

This document the API to retrieve the list of Active Unit Type

How it should work:

• 3rd party API call a UNTE Endpoint

Option 1 - Active Unit types:

Input:

active

Output:

The list of active unit types

• Designation (Office, Hotel, Flat, Room, etc...)

The SQL query to retrieve the list of Unit Types:

Below is the query to list this in the UNTE Database

SELECT `designation` 
FROM `ut_unit_types`
WHERE `is_obsolete` = 0
;

Option 1 - All Unit types:

Input:

all

Output:

The list of ALL unit types:

• Unit type designation (Office, Hotel, Flat, Room, etc...)
• 1 if this is INACTIVE (obsolete) or 0 if this is ACTIVE

The SQL query to retrieve the list of Unit Types:

Below is the query to list this in the UNTE Database

SELECT `designation` 
  , `is_obsolete`
FROM `ut_unit_types`
;

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 [email protected] is created in Unee-T by a user [email protected].

The user [email protected] will need to grant access to several units in his organization:

• Unit 1-A
• Unit 2-A

The user [email protected] 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 [email protected] can only see the API key apikey_A associated to [email protected].
User [email protected] 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 [email protected] "creates" the same user [email protected] in Unee-T.

The user [email protected] will need to grant access to several units in his organization:

• Unit 1-B
• Unit 2-B

The user [email protected] 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 [email protected] can only see the API key apikey_B associated to [email protected].
User [email protected] 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

As part of #3 we also need an endpoint so that the 3rd party can check if the unit has been correctly created:

How it should work:

• 3rd party calls an endpoint
• 3rd party specifies the record it wants to retrieve
• 3rd party specifies the information it wants to retrieve for this record
• End point returns the information

Background information:

The information is available in the UNTE Database in the table unte_api_add_unit.
From this table, it is possible to retrieve the following information

• mefe_unit_id: The MEFE id of the unit
• uneet_created_datetime: the timestamp when the unit was created in Unee-T
• is_api_success:
  • 1 if the unit was created correctly
  • 0 if the there was an error while creating the unit.
  • NULL we have no information (this is the initial state until we receive a reply from the downstream systems)
• api_error_message: the error message if applicable.

The different ways to retrieve the information:

Option 1:

In this option the 3rd party only needs the information from it's internal source of truth

User Input:

The user sends the following information as part of the payload:

• MANDATORY organizationKey varchar(255): The UNTE API key for the 3rd party.
  This key MUST exist in the table unte_api_keys or else there will be an error.
• MANDATORY externalId varchar(255): the Unique ID of the unit in the source system: the system where the user information is coming from. This cannot be empty. (see #3)
• OPTIONAL externalSystem varchar(100): This is the name of the source of truth for unit information from the 3rd party.
• OPTIONAL tableInExternalSystem varchar(100): This is the table where the unit information are stored in the the source of truth for unit information from the 3rd party.
• OPTIONAL infoNeeded: this could be one of the following values:
  • All - this will be the default value if nothing is specified.
  • mefeUnitId
  • createdDatetime
  • created
  • errorMessage

Output:

Based on the value specified in infoNeeded

All or [unspecified]:

return all the information:

• mefeUnitId: the mefe unit id of the unit
• createdDatetime: The timestamp (Z) when the unit was created in Unee-T
• status: This can either be
  • 1: success
  • 0: error
  • NULL: we have no information about the status of the request, request is still pending.
• errorMessage: The error message (if applicable)

mefeUnitId:

return the information:

• mefeUnitId: the mefe unit id of the unit

createdDatetime:

return the information:

• createdDatetime: The timestamp (Z) when the unit was created in Unee-T

status:

return the information:

• status: This can either be
  • 1: success
  • 0: error
  • NULL: we have no information about the status of the request, request is still pending.

errorMessage:

return the information:

• errorMessage: The error message (if applicable)

Option 2:

In this option the 3rd party only need to have stored the requestId that was generated when the unit creation was request (see #3)

User Input:

The user sends the following information as part of the payload:

• MANDATORY organizationKey varchar(255): The UNTE API key for the 3rd party.
  This key MUST exist in the table unte_api_keys or else there will be an error.
• MANDATORY requestId varchar(255): the Unique ID of the request that was sent when the 3rd party requested the unit to be created (see #3)
• OPTIONAL infoNeeded: this could be one of the following values:
  • All - this will be the default value if nothing is specified
  • mefeUnitId
  • createdDatetime
  • created
  • errorMessage

Output:

Based on the value specified in infoNeeded

All or [unspecified]:

return all the information:

• mefeUnitId: the mefe unit id of the unit
• createdDatetime: The timestamp (Z) when the unit was created in Unee-T
• status: This can either be
  • 1: success
  • 0: error
  • NULL: we have no information about the status of the request, request is still pending.
• errorMessage: The error message (if applicable)

mefeUnitId:

return the information:

• mefeUnitId: the mefe unit id of the unit

createdDatetime:

return the information:

• createdDatetime: The timestamp (Z) when the unit was created in Unee-T

status:

return the information:

• status: This can either be
  • 1: success
  • 0: error
  • NULL: we have no information about the status of the request, request is still pending.

errorMessage:

return the information:

• errorMessage: The error message (if applicable)

How to get the information from the UNTE DB:

This is done by passing some SQL variables and calling a specific procedure

The variables:

@organization_key: This can NOT be NULL
@request_id:

• This MUST be NULL if @external_id is NOT NULL (this means we are in Option 1)
• This can NOT be NULL IF @external_id is NULL (this means we are in Option 2)
  @external_id: This can NOT be NULL
• This can NOT be NULL if @request_id is NULL (this means we are in Option 1)
• This MUST be NULL IF @request_id is NOT NULL (this means we are in Option 2)
  @external_system: This MUST be NULL
• IF this is NOT specified by the 3rd party
• IF @request_id is NOT NULL (this means we are in Option 2)
  @table_in_external_system: This MUST be NULL
• IF this is NOT specified by the 3rd party
• IF @request_id is NOT NULL (this means we are in Option 2)
  @info_needed: This MUST be NULL if this is NOT specified by the 3rd party

The SQL syntax:

SET @organization_key = [organizationKey];
SET @request_id = [requestId];
SET @external_id = [externalId];
SET @external_system = [externalSystem OR NULL];
SET @table_in_external_system = [tableInExternalSystem OR NULL];
SET @info_needed = [infoNeeded OR NULL];
CALL `proc_unte_api_check_unit_creation` ;

How it should work:

Input:

UPDATE - THIS IS OBSOLETE. See #3 (comment) for the updated version

• actionType: "CREATE_UNIT",
• external_property_id: the Unique ID of the unit in the source system: the system where the user information is coming from. This cannot be empty.
• 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)
• tower : the block where the unit is located. if empty, we use 1.
• creatorAPIKey: the MEFE API Key of the user requesting the creation of the unit
• name: a name for the unit (string)
• type: The type of the unit. See the list of MEFE authorized unit type
• moreInfo: Free text to add more information about the unit (excluding address information)
• streetAddress: Street address and unit number if applicable
• city: The city (a string)
• state: regional subdivision or administrative region (ex: California)
• zipCode: ZIP or Postal Code
• country: the 2 letter ISO code for the country example: SG or AU
• Parent Unit ID: the MEFE unit Id of the parent unit (ex: MEFE Unit Id of the building if the unit created is a flat or MEFE Unit Id of the flat if the unit created is a room).

Output:

Success:

Return:

• unitId: (the MEFE unit Id)
• timestamp: date and time (Z) when the unit was successfully created

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 unit.
• Unee-T Enterprise uses the MEFE API to create a unit.

How it should work:

Input:

• requestorAPIKey: the MEFE API Key of the user requesting the modification of the user
• ModifiedUserApiKey: the MEFE API Key for the user who needs to be added
• Fields to be modified:
  • 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:

Return timestamp: date and time (Z) when the unit was successfully modified

Failure:

Include descriptive error message.

What happens in the back end:

• Unee-T Enterprise checks if the user associated to the requestorAPIKey is allowed to Edit the user.
• Unee-T Enterprise uses the MEFE API to edit a user to edit the user.

One of the requirement of #3 is that the 3rd party uses a valid Country code when a unit is created or modified.

This document the API to retrieve the list of possible country codes.

How it should work:

• 3rd party API call a UNTE Endpoint

Option 1 - Active Unit types:

Input:

not applicable (no input needed)

Output:

The list of countries and country codes

• Country Code (AU, SG, FR, ...)
• Country Name (Australia, Singapore, France, ...)

The SQL query to retrieve the list of country codes:

Below is the query to list this in the UNTE Database

SELECT `country_code` 
  , `country_name`
FROM `property_groups_countries`
;

How it should work:

Input:

• MEFE API Key for the user requesting the addition (requestorApiKey)
• MEFE API Key for the user who needs to be removed (removedUserApiKey)
• MEFE unit ID for the unit

Output:

Success

Return timestamp: date and time (Z) when the user was successfully removed from the unit.

Failure

Include descriptive error message

What happens in the back end:

• Unee-T Enterprise checks if user requestorUserId is allowed to remove the user from that role in the unit.
• Unee-T Enterprise uses the MEFE API to remove a user from a role in a unit.

For example /persons maps to the persons table.

https://media.dev.unee-t.com/2019-04-04/tables.txt

What are the others?

How it should work:

Input:

• MEFE API Key for the user requesting the addition (requestorApiKey)
• MEFE API Key for the user who needs to be added (addedUserApiKey)
• MEFE unit ID for the unit
• Unee-T Enterprise Unee-T role id for the role selected for that user

Output:

Success

Return timestamp: date and time (Z) when the user was successfully added to the unit.

Failure

Include descriptive error message

What happens in the back end:

• Unee-T Enterprise checks if the user associated to the the requestorAPIKey is allowed to add the user to the unit.
• Unee-T Enterprise uses the MEFE API to add a user to a role in a unit.