ERP Data Exchange Specifications

This document specifies the Allthings ERP Data Exchange format.

Contents

  1. Import Process Outline

  2. CSV file specifications

    1. uuidRemappings.csv
    2. properties.csv
    3. groups.csv
    4. units.csv
    5. utilisationPeriods.csv
    6. tenantCheckIns.csv
    7. tenants.csv
    8. agents.csv
    9. propertyTeams.csv
    10. userRelations.csv
    11. agentPermissions.csv
    12. serviceProviders.csv
    13. collections.csv
    14. collectionAssignments.csv
    15. manifest.json
  3. Data Types

    1. Agent Type
    2. Country Type
    3. Date Type
    4. Import Type Enumerable Type
    5. Phone Number Type
    6. Resource Enumerable Type
    7. String Type
    8. UUID Type

Import Process Outline

Customer Support will provide a data upload location (an AWS S3 Bucket). Uploading a set of CSVs and a manifest.json file constitutes an Import Job. The manifest.json file acts as a trigger to begin the import process for the uploaded set of CSVs. This file must be uploaded last to indicate that the Import Job should begin the import.

CSV file specifications

There are 14 recognised CSV files: uuidRemappings.csv, properties.csv, groups.csv, units.csv, userRelations.csv utilisationPeriods.csv, tenantCheckIns.csv, tenants.csv, propertyTeams.csv, agents.csv, agentPermissions.csv, serviceProviders.csv, collections.csv, collectionAssignments.csv. It is not required that each CSV be included in each Import Job. For example, it is possible to include only the agents.csv file, or any other combination. However, when inserting new data, the necessary data to resolve the foreign ID relationships must also be included. Issues in resolving data relationships will result in an error, terminating the complete Import Job.

Global Observations:

  • Columns can be in any order
  • First row in CSV file must contain column field name
  • Column field names are case-sensitive
  • Unless noted otherwise, all fields are required when importType is insert
  • Only UUID type fields required when importType is update
  • Files must use the UTF-8 character encoding

uuidRemappings.csv

The uuidRemappings.csv file allows for the remapping of UUIDs on resources. Note: The uuidRemappings.csv cannot be combined with other CSV files within a single import. Doing so will result in an import error.

Fields

Field Type Description
importType Import Type Always use "update"
resource Resource The type of resource these UUIDs refer to
oldUuid UUID The previous UUID
newUuid UUID The new UUID

Example

properties.csv

The properties.csv file imports property resource data.

Fields

Field Type Description
importType Import Type One of:insert, update
id UUID Your UUID for this property
name string The property name
propertyOwner string Optional name of the property owner
billingPeriodStartDate Date Optional billing period start date
billingPeriodEndDate Date Optional billing period end date

Example

groups.csv

The groups.csv file imports group data.

Fields

Field Type Description
importType Import Type One of:insert, update
id UUID Your UUID for the group
propertyId UUID The foreign UUID of the property the group belongs to (properties.csv id)
name string
country Country
city string
streetName string The name of the street the structure is located on, e.g. Kaiser-Joseph-Strasse
houseNumber string The number of the structure on the street, e.g. 123
zipCode Postal Code
propertyOwner string Optional name of the property owner
billingPeriodStartDate Date Optional billing period start date
billingPeriodEndDate Date Optional billing period end date

Example

units.csv

The units.csv file imports unit data. It allows for associating groups with units.

Fields

Field Type Description
importType Import Type One of:insert, update
id UUID Your UUID for the unit
groupId UUID The foreign UUID of the group the unit belongs to (groups.csv id)
name string
propertyOwner string Optional name of the property owner
billingPeriodStartDate Date Optional billing period start date
billingPeriodEndDate Date Optional billing period end date

Example

utilisationPeriods.csv

The utilisationPeriods.csv describes utilisation periods.

Fields

Field Type Description
importType Import Type One of:insert, update, delete
id UUID Your UUID for the utilisation period
unitId UUID The foreign UUID of the unit the utilisation period belongs to (units.csv id)
startDate Date
endDate Date

Example

tenants.csv

The tenants.csv file describes registration codes for a tenant.

Fields

Field Type Description
importType Import Type One of:insert, update
id UUID Your UUID for the tenant
registrationCode string
email string Optional
phone Phone Number Optional
name string Optional

Example

tenantCheckIns.csv

The tenantCheckIns.csv file describes the relation between a tenant and a utilisation period.

Fields

Field Type Description
importType Import Type One of:insert, update
utilisationPeriodId UUID The foreign UUID of the utilisation period the tenant check-in is for (utilisationPeriods.csv id)
tenantId UUID The foreign UUID of the tenant tenant check-in is for (tenantss.csv id)

Example

agents.csv

The agents.csv file describes agent-user account data.

Fields

Field Type Description
importType Import Type One of:insert, update
id UUID Your UUID for the agent
email string
firstName string
lastName string
phone Phone Number Optional
serviceProviderId UUID Optional

Example

propertyTeams.csv

The propertyTeams.csv file describes the relation between a property and an agent.

Fields

Field Type Description
importType Import Type One of:insert, or delete
propertyId UUID The foreign UUID of the property that the team belongs to (properties.csv id)
agentId UUID The foreign UUID of the agent that belongs to the team (agents.csv id)
validFromDate DateTime Optional start date of the validity of the relation (if provided validToDate is required as well)
validToDate DateTime Optional end date of the validity of the relation (if provided validFromDate is required as well)

Example

userRelations.csv

The userRelations.csv file describes the relation between an agent and a resource

Fields

Field Type Description
importType Import Type One of:insert, or delete
agentId UUID The foreign UUID of the agent that is responsible for the channel path (agents.csv id)
resourceId UUID The foreign UUID of the resource that the agent belongs to (resource.csv)
resourceType Resource Type The type of the resource being referenced by the resourceId (property)
validFromDate DateTime Optional start date of the validity of the relation (if provided validToDate is required as well)
validToDate DateTime Optional end date of the validity of the relation (if provided validFromDate is required as well)
jobRole string Optional

Example

agentPermissions.csv

The agentPermissions.csv file describes the agents permissions on a certain resource via predefined agentTypes

Field Type Description
importType Import Type One of:insert, or delete
resourceType Resource Type The type of the resource being referenced by the resourceId (e.g. property)
resourceId UUID The foreign UUID of the resource that the agent belongs to (resource.csv)
agentId UUID The foreign UUID of the agent that is responsible for the channel path (agents.csv id)
agentType Agent Type Defines the type of an agent
validFromDate DateTime Optional start date of the validity of the relation (if provided validToDate is required as well)
validToDate DateTime Optional end date of the validity of the relation (if provided validFromDate is required as well)

Example

serviceProviders.csv

The serviceProviders.csv file describes a service providers name + address

Field Type Description
importType Import Type One of:insert, or update
id UUID Your UUID for the service provider
name string Name of the service provider
country Country
city string
streetName string
houseNumber string
zipCode Postal Code
phone Phone Number Optional

Example

collections.csv

The collections.csv file describes a collection

Field Type Description
importType Import Type One of:insert, or update
id UUID Your UUID for the collection
name string Name of the collection

Example

collectionAssignments.csv

The collectionAssignments.csv file describes the relation between a collection and a resource

Field Type Description
importType Import Type One of:insert, update or delete
collectionId UUID The uuid of the collection
resourceType Resource Type The type of the resource being referenced by the resourceId (e.g. property)
resourceId UUID The foreign UUID of the resource that the collection belongs to (resource.csv)

Example

manifest.json

The manifest.json file controls the Import Jobs execution and behavior. The upload/presence of a manifest.json file at a Job Import upload location triggers the import process. While Customer Support will set up default configuration for each ERP Import Customer, the manifest.json file also allows for some customisation of options. These options are outlined here:

Fields

Field Type Description
agentPermissions Array of Strings List of permissions to be set for agent imported in the Property Teams file E.g. to set permissions for pinboard and documents ['pinboardAdmin', 'documentAdmin']
autoImport boolean Controls whether to automatically import, or to send confirmation email first
locale ISO-639 Language Codes and ISO-3166 Country Codes Default locale. E.g. locale for new agents. en_US, de_DE
receiveAdminNotifications boolean Receives Notification-Mails for Tickets with no Assignee. Default setting is true
reportEmails Array of Strings or a combination of email address + report level either error or success List of email addresses which should receive report emails for this job
unitType string Controls the type of import Units, one of type 'rented' or 'owned'

Examples

if no default option should be overwritten, the manifest.json should include at least an empty JSON-Object:

Data Types

The following table describes the expected data formats of data provided in the CSV files. Data is validated before import, and any errors are reported. Import Jobs with validation errors are not processed. In other words, a single invalid field will terminate the entire import process for all CSV files in the Import Job.

Type Description Example
Agent Type One of: agent, externalAgent externalAgent
Country [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. CH, DE, FR
Date [ISO 8601 Calendar Date](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates) (yyyy-mm-dd) 2001-05-11, 2018-03-06, 2063-04-05
DateTime [ISO 8601 Combined date and time representation](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) 2015-01-17T18:23:02+06:45, 2015-01-17T18:23:02Z
Import Type One of:insert, update, delete insert
Phone Number plus symbol + followed by only numbers (5-20 characters), no formatting +4134567890
Postal Code Only numbers and hyphens 123-4567, 3457, 93012
Resource One of:property, group, unit, utilisationPeriod group
String any UTF-8 string This is OK, This 1 is also good., これも大丈夫
UUID [RFC 4122 version 4 (random) UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) 71b63eef-3c50-4632-924c-b3c59f45c0ef, 71fc860f-7fa9-4012-a32e-88be33d607af, bf9d6003-19a2-4c3e-b68c-828c45d2cf10