for e.g. next steps here is how to query that given that a new unit has been created in the relevant table (what table is this btw?), demonstrate how to find the unitId from which table. I.e. what is the SQL query to know that this new unitId has been created.

Furthermore how to query if there was an error or the job is yet to be run.

from enterprise-rest-api.

How the unit creation works in UNTE:

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

• 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)
• organization_id: a unique ID attached to the API key for the Master user for the UNTE enterprise account
• tower : the block where the unit is located. By default this is 1.
• external_property_type_id: The type of the unit. See the list of MEFE authorized unit type

After the user creation request is sent to UNTE:

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

SELECT 
  `unee_t_mefe_unit_id`
  , `uneet_created_datetime`
  , `is_mefe_api_success`
  , `mefe_api_error_message`
FROM `ut_map_external_source_units`
WHERE `external_property_id` = "[external_person_id]"
  AND `external_system` = "[external_system]"
  AND `table_in_external_system` = "[table_in_external_system]"
  AND `organization_id` = "[organization_id]"
  AND `tower` = "[tower]"
  AND `external_property_type_id` = "[external_property_type_id]"
;

This will return a single record where:

• unee_t_mefe_unit_id is a STRING: The MEFE unit ID for this unit
• uneet_created_datetime is a TIMESTAMP (Z) the date and time when the unit was created. If this is NULL then we have not received any reply yet.
• is_mefe_api_success is either 1 (TRUE), 0 (FALSE) or NULL (we have not received any reply yet)
• mefe_api_error_message is a STRING: the error message we received if any. If it is NULL we have not received any reply yet, if it is empty '' then there was no error reported.

from enterprise-rest-api.

@kaihendry I have create the table unte_api_add_unit in the DEV/Staging environment

This is the table that needs to be updated (with a SQL INSERT statement) when a 3rd party requests the creation of a new unit via the UNTE API.

The fields that are expected to be populated:

The API is expected to update the following fields in the table unte_api_add_unit:

Info coming From the user calling the API:

Mandatory fields:

• external_id varchar(255): This is the unique ID in the source of truth for unit information from the 3rd party.
• organization_key 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 and it will be impossible to insert the record in the table.
• unee_t_unit_type varchar(100): The type of the unit.
  This MUST match one of the existing designation value for unit types as listed in the table ut_unit_types or else there will be an error and it will be impossible to insert the record in the table.
• designation varchar(255): The name of the unit.
• country_code varchar(10): The 2 letter ISO country code where the unit is located (ex: FR, AU, SG, US, etc...)
  This MUST match one of the existing country_code in the table property_groups_countries or else there will be an error and it will be impossible to insert the record in the table.
• mgt_cny_default_assignee varchar(255): The API Key for the user that will be assigned as the default assignee for this unit when an new case is created
  This MUST meet the following criteria:
  • The user is a "Public" user
  • The user is a user in the role "Management Company"
  • The MEFE user API key must exist.
    or else there will be an error and it will be impossible to insert the record in the table.

Optional fields:

• external_system_id varchar(100): this is the name of the source of truth for unit information from the 3rd party.
• external_table 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.
• creation_method varchar(255): How this request was generated. This is a placeholder so that a 3rd party that have several systems using the MEFE API can track which system was used to generate this entry.
• parent_mefe_id varchar(255): the MEFE ID of the unit or object that is a parent for this unit (ex: the MEFE id for the Flat if we request the creation of a room).
  This unit MEFE ID MUST exist in the table ut_map_external_source_units or else there will be an error and it will be impossible to insert the record in the table.
• tower varchar(50): the block or tower in the development (if applicable).
• unit_id varchar(255): the unique id of the unit in the building (ex: #01-05)
• address_1 varchar(50): first part of the address for the unit
• address_2 varchar(50): second part of the address for the unit
• zip_postal_code varchar(50): the ZIP or postal code for the unit
• state varchar(50): the state or admnistrative region (ex: CAL, California, NSW,, etc...)
• city varchar(50): The city (ex: Paris, New York, Singapore, ...)
• description text : A longer description of the unit
• count_rooms int(10): Number of rooms in the unit
• surface int(10): The surface of the unit
• surface_measurement_unit varchar(10): Either sqm (Square Meters) or sqf (Square Feet)
• number_of_beds: Number of beds in the unit
• landlord_default_assignee varchar(255): The API Key for the user that will be assigned as the default assignee in this role for this unit when an new case is created
  This MUST meet the following criteria:
  • The user is a "Public" user
  • The user is a user in the role "Management Company"
  • The MEFE user API key must exist.
    or else there will be an error and it will be impossible to insert the record in the table.
• tenant_default_assignee varchar(255): The API Key for the user that will be assigned as the default assignee in this role for this unit when an new case is created
  This MUST meet the following criteria:
  • The user is a "Public" user
  • The user is a user in the role "Management Company"
  • The MEFE user API key must exist.
    or else there will be an error and it will be impossible to insert the record in the table.
• agent_default_assignee varchar(255): The API Key for the user that will be assigned as the default assignee in this role for this unit when an new case is created
  This MUST meet the following criteria:
  • The user is a "Public" user
  • The user is a user in the role "Management Company"
  • The MEFE user API key must exist.
    or else there will be an error and it will be impossible to insert the record in the table.

Info that are automatically captured:

There is no need for any user input

• request_id VARCHAR(255) the unique id for this request. This is expected to be generated by the request itself.
  The MySQL command to generate a UUID is

UUID();

• syst_created_datetime: the time stamp when the request was sent to the UNTE database.
  The MySQL command to generate a timestamp is

NOW();

from enterprise-rest-api.

curl http://localhost:3000/unit/fce0a6ac-1958-4eba-9d22-c3d4f087ad09 > /tmp/payload.json

https://media.dev.unee-t.com/2019-07-09/payload.json

I chose the REST verb unit here. Let me know if it should be changed.

Trying to generate the skeleton of the payload JSON that is used to insert a row into the unte_api_add_unit table.

I noticed organization_key was checked, but not:

• external_id
• unee_t_unit_type
• designation
• country_code
• mgt_cny_default_assignee

Is this going to be implemented in the schema?

from enterprise-rest-api.

What should be returned on a successful insert? A copy in JSON of what was set?

from enterprise-rest-api.

I noticed organization_key was checked, but not:

external_id
unee_t_unit_type
designation
country_code
mgt_cny_default_assignee

@kaihendry: we do have constraints in the DB schema already for the following fields:

• agent_default_assignee
• landlord_default_assignee
• mgt_cny_default_assignee
• tenant_default_assignee
• parent_mefe_id
• mefe_unit_id
• organization_key
• unee_t_unit_type

I just realized the constraint for country code seem to be missing... I'll fix that...

The constraints in the DB schema are defined in the schema for the table:

(...)
CONSTRAINT `api_add_unit_api_key_default_assignee_agent_must_exist` FOREIGN KEY (`agent_default_assignee`) REFERENCES `ut_map_external_source_users` (`unee_t_mefe_user_api_key`) ON UPDATE CASCADE,
  CONSTRAINT `api_add_unit_api_key_default_assignee_landlord_must_exist` FOREIGN KEY (`landlord_default_assignee`) REFERENCES `ut_map_external_source_users` (`unee_t_mefe_user_api_key`) ON UPDATE CASCADE,
  CONSTRAINT `api_add_unit_api_key_default_assignee_mgt_cny_must_exist` FOREIGN KEY (`mgt_cny_default_assignee`) REFERENCES `ut_map_external_source_users` (`unee_t_mefe_user_api_key`) ON UPDATE CASCADE,
  CONSTRAINT `api_add_unit_api_key_default_assignee_tenant_must_exist` FOREIGN KEY (`tenant_default_assignee`) REFERENCES `ut_map_external_source_users` (`unee_t_mefe_user_api_key`) ON UPDATE CASCADE,
  CONSTRAINT `api_add_unit_mefe_id_must_exist` FOREIGN KEY (`mefe_unit_id`) REFERENCES `ut_map_external_source_units` (`unee_t_mefe_unit_id`) ON UPDATE CASCADE,
  CONSTRAINT `api_add_unit_mefe_id_parent_must_exist` FOREIGN KEY (`parent_mefe_id`) REFERENCES `ut_map_external_source_units` (`unee_t_mefe_unit_id`) ON UPDATE CASCADE,
  CONSTRAINT `api_add_unit_organization_key_must_exist` FOREIGN KEY (`organization_key`) REFERENCES `unte_api_keys` (`api_key`) ON UPDATE CASCADE,
  CONSTRAINT `api_add_unit_unit_type_must_exist` FOREIGN KEY (`unee_t_unit_type`) REFERENCES `ut_unit_types` (`designation`) ON UPDATE CASCADE

from enterprise-rest-api.

What should be returned on a successful insert? A copy in JSON of what was set?

IMO we should return the request_id that was just generated.

A copy in JSON of what was set?

Might be good to read back what was the 3rd party request too yes.

from enterprise-rest-api.

I just realized the constraint for country code seem to be missing... I'll fix that...

Fixed

from enterprise-rest-api.

I chose the REST verb unit here. Let me know if it should be changed.

No issue for me

from enterprise-rest-api.

@kaihendry can you please include the endpoint and an example of the payload like it's done below
POST to
[enter the URL for the endpoint]
with the following request body:

{
    "input_a": "...",
    "input_b": "..."
}

This request should respond with the following details:

{
    "field_1": "value",
    "field_2": "value"
}

This is so I can create a proper documentation for this API.

from enterprise-rest-api.

This is what Postman does. Document our APIs. https://s.natalian.org/2019-07-09/unit.mp4

E.g. https://documenter.getpostman.com/view/3704379/SVSEtB4z?version=latest#40016185-0995-47a2-9610-0f0c28023049

We could put this on a custom domain like api.unee-t.com

from enterprise-rest-api.

We could put this on a custom domain like api.unee-t.com

I like that idea TBH
@nbiton do you think we should make the move for the other APIs too?

from enterprise-rest-api.

Sounds problematic to implement. We'll need a way to proxy some requests to MEFE and not others. I think it could be more trouble than what it's worth

from enterprise-rest-api.

Sounds problematic to implement. We'll need a way to proxy some requests to MEFE and not others. I think it could be more trouble than what it's worth

OK makes sense.
Based on this it'll probably less confusing to have an URL that looks dedicated to the Unee-T Enterprise environment IMO.

from enterprise-rest-api.

https://s.natalian.org/2019-07-10/mandatory-optional-internal.mp4

mandatory

external_id,
organization_key
unee_t_unit_type
designation
country_code
mgt_cny_default_assignee

optional

external_system_id
external_table
creation_method
parent_mefe_id
tower
unit_id
address_1
address_2
zip_postal_code
state
city
description
count_rooms
surface
surface_measurement_unit
number_of_beds
landlord_default_assignee
tenant_default_assignee
agent_default_assignee

set on insert in model

request_id
syst_created_datetime

internal

(not exposed)

id_unte_api_add_unit
creation_system_id
update_system_id
updated_by_id
update_method
is_obsolete
order
s_creation_needed_in_unee_t
mefe_unit_id
uneet_created_datetime
is_api_success
api_error_message

from enterprise-rest-api.

Can I close this bug?

from enterprise-rest-api.

Can I close this bug?

Let's close this once I've done a few end to end tests to see if all works as intended

from enterprise-rest-api.