Skip to main content

Bulk Import/Update

Paul Schneider
  • Updated

Several API calls exist to support synchronizing data into the Building Engines environment in large, bulk uploads. Bulk uploads can occur when loading initial data into the system or when doing changes in mass. These uploads are JSON payloads but allow creation/update of a large number of buildings, spaces, and users.

All bulk operations perform a create or update pass where, if the payload includes either a Building Engines ID (id) or an External Key (external_key) string, we will seek an existing record to update before creating a new one. In this way, repeated entries are not duplicated, and existing values can be updated.

Each successful call will return a response containing a single job_id UUID value in a JSON object. This indicates the bulk request is queued for processing. Background processing time may vary due to system load and the size of the request.

The calling application can then perform:

   GET /jobs/<Job ID>

And will get back either a response value with a single key “detail” indicating the job is still processing or your will get back a response with both a detail element, describing the result in a string, and an array of objects which will include:

  • id: The Building Engines ID of the created or updated object
  • name: The name of the object in question
  • external_key: The external key, or blank if not given for the object

At present, both in-progress and completed return an HTTP 200 (OK) but in the near future we will return HTTP 200 (OK) for a completed job and HTTP 202 (ACCEPTED) for an incomplete job. If any error exists in the payload being processed, we will return an HTTP 400 (BAD REQUEST) with the payload directing what fields or data is in error.

A new feature allows the primary_contact_id to be set. This is a Prism user account UUID and will set them as the primary contact point for this building.

 

Creating Buildings

Given your Manager Organization UUID value, address the following URL:

   POST /bulk/<PMO ID>/buildings

The payload is an array of JSON objects including the following fields:

  • id: Building Engines ID UUID if updating an existing record
  • external_key: External unique identification string used to create a new record or update an existing one
  • pmo_id: Building Engines ID of the management organization responsible for this building.
    This allows specification of an alternative management organization if one exists in the account.

The default is the account primary management organization.

  • account_id: Building Engines ID of the account related to this building
  • name: Name of the building
  • street_address: Street address
  • street_address_2: 2nd line of street address
  • city: City of the building
  • state: State: should use the standard, ISO short form; for non-US this may reflect a region, prefecture, etc.
  • zip_code: Postal code
  • country: Country: should use the standard, ISO short form
  • industry: Must be one of: commercial, retail, industrial, land, medical, mixed, other
  • measured_area: Volume of the property in square feet or square meters. Specify as a string with an integer followed by units which must be sq_ft or sq_m.
    • Example: “12500 sq_ft”
  • phone
  • website
  • organizational_goal: Must be one of: mixed, responsive, lean
  • is_active: Indicates this building is active. This is the default. A PATCH with a False value will indicate the building should be deactivated.
  • created_at: ISO 8601 formatted date and time
  • updated_at: ISO 8601 formatted date and time
  • primary_contact_id: Prism UUID of the Primary Contact of this Building
  • primary_contact_external_key: External Key of Primary Contact for this building
  • Is_synchronized: Indicates this data has been synchronized and should not be edited directly in the Prism UI
  • custom_fields: An array of JSON objects including a field_name and a value to set custom fields on the Building.
    • The custom field must have been created prior to this usage.

An example payload follows:

“buildings_data”: [
{
"external_key": "142808",
"is_synchronized": true, 
“is_active”: true, 
“pmo_id”: “62d093f8-4fdd-4c1b-b23f-e7710a995b85”, 
"name": "Stone Oak Bldg A", 
"street_address": "20855 Stone Oak Pkwy", 
"street_address_2": "Building 1",
"city": "San Antonio",
"state": "TX",
"zip_code": "78258",
"country": "USA",
"industry": "commercial",
"num_floors": 1,
"measured_area": "99852 sq_ft",
"timezone": "US/Central",
"latitude": 29.652174,
"longitude": -98.458659,
"custom_fields": [{
"field_name": "cost_center",
"value": "CC/XXX"
}],
"primary_contact_external_key": "78123" 
}
]

In the above example, the “pmo_id” can be obtained by querying the /organizations endpoint.

 

Creating Spaces

The space call allows creation of spaces for buildings. There are specialized endpoints to create special types of spaces including Suites, Floors, Common Areas, and more.

The call is:

POST /bulk/<PMO ID>/spaces

There are different types of spaces including:

  • Floor
  • Space
  • Suite

If a parent is indicated, the parent is expected to be created before the child.

The payload common to all of these include the following fields:

  • resourcetype: Must be one of: Floor, Space, Suite
  • building_id: Building Engines ID of Building; must include this or a building_external_key
  • building_external_key: External unique identifier of the Building
  • id: Building Engines ID UUID if updating an existing record
  • external_key: External unique identification string used to create a new record or update an existing one
  • parent_id: Building Engines ID of the parent space
  • parent_external_key: External unique identifier of the parent space
  • name: Name of the space
  • description: Description of the space
  • synced: Indicates that the data is being synchronized from an external source and thus should be read-only
  • is_exterior: Indicates this space is outside
  • is_common: Indicates this space is common to many individual tenants
  • is_active: Indicates this space is active. This is the default. A PATCH with a False value will indicate the building should be deactivated.

Additionally, for a Suite type, you must add one of the following:

  • floor_id: Building Engines ID of the Floor that contains the suite
  • floor_external_key: External key value for the Floor

An example payload for this:

{
“data”: [
{
“building_external_key”: “142808”, 
“resourcetype”: “Floor”,
“name”: “1st Floor"
}, 
{
“building_external_key”: “142808”, 
“resourcetype”: “Floor”,
“name”: “2nd Floor”
},
{
“building_external_key”: “142808”, 
“resourcetype”: “Floor”,
“name”: “Roof”
}
]
}

 

Creating Users

To create users, call:

   POST /bulk/<PMO ID>/users

As with the other calls, the payload is an array including:

  • id: Building Engines ID UUID if updating an existing record
  • external_key: External unique identification string used to create a new record or update an existing one
  • authentication_type: Must be one of: local or sso
  • authentication_service_id: Authentication service ID instance from the Building Engines service; based on the Account and SSO setup
  • email: Email of user
  • first_name: User first name
  • last_name: User last name
  • phone: User phone number
  • job_function_id: Job Function ID
  • organization_deprecated_id: ID of the primary organization for the user
  • organization_external_key: External Key for the organization of the user
  • identifier: Employee ID of the user in question
  • building_ids: Array of building ID values to associate this user to
  • building_external_keys: Buildings for which the user has access
  • is_active: Indicates this user is active. This is the default. A PATCH with a False value will indicate the user should be deactivated.
  • building_association_rule: Rather than specify specific buildings by ID or external key, the keyword “all” here indicates the user is in all buildings of their company.

We also allow “append” (the default) to indicate that listed buildings should be added to existing ones.

Finally you can specify “set” to indicate that the user should be in only the buildings indicated.

Notes:

On Building External Keys, this is a JSON payload including Building External Keys and, optionally, Building Suite External Keys. This can associate a user with a building and optionally a suite within the building.

The structure is as follows:

(JSON)

{
“building external key”: [ “building suite external key”, ... ]
}

Using this structure, one can declare simple building membership by supplying an empty array. More than one building key can be provided.

An example payload showing this follows:

{
"users_data": [
{
"authentication_type": "sso",
"authentication_service_id": “89d093f8-4...23f-e8c30a119a96”, 
"identifier": "O624508",
"external_key": "O624508",
"email": user_email_1,
"first_name": "Pedro",
"last_name": "Garcia",
"phone": "+13026345808",
"job_function_id": “88d093f8-4...23f-ff9c30a110001”, 
"is_synchronized": True,
"custom_fields": [{
"field_name": "cost_center",
"value": "31213"
}]
}]
}

In the above example, the job_function_id can be obtained by the /job_functions endpoint and similarly, the authentication endpoint can support the authentication_service_id.

An example of deactivating a user is as follows:

{
"users_data": [{
"external_key": "O624508", 
“is_active”: false
]}
}

 

Related articles

Powered by Zendesk