Creating a new ObjectAssignment

Creating a new object assignment requires a few steps.

  1. Create a new empty objectAssignment
  2. Updating required data
  3. Getting and setting a valid address
  4. Updating objectAssignment
  5. Save objectAssignment
  6. Understanding error messages

Prerequisites

ObjectAssignments are one of our most complex objects, it is important to follow our Swagger documentation to ensure you’re sending the right properties with the right value types.

Our Swagger documentation has two controllers that might be confusing; Assignments and ObjectAssignments. The Assignment Controller is used to fetch lists of assignment types (objects, projects, object types, acquisitions and acquisition objects) and are not relevant for this workflow, just the ObjectAssignment Controller is.

Need some help navigating our Swagger Documentation? You can find a 101 here.

Create a new empty objectAssignment

The best way to start creating a new objectAssignment is to let our API create an empty assignment for you. You can do so by calling the defineNew method on the ObjectAssignmentController. This call requires you to set the following required properties: employeeId, forRent, forSale, listingType, officeId, realEstateGroup. If you leave any of these properties empty or without a valid value it will result in errors. You can check our Swagger documentation for the expected value types.

Updating required data

Some required properties should not be updated after the objectAssignment is first saved (and losing it’s isNew status), these are:

  • forSale
  • forRent
  • realEstateGroup
  • listingType

Getting and setting a valid address

An objectAssignment most recognizable property is its address. To ensure an address is formatted well there are a few steps to follow:

  1. Implement your own solution for searching location strings.
    This is totally up to you, you can use Google maps, OpenMaps or a simple text input. Important is that is produces a string that is usable by our Geo Controller.
  2. Call our Geo Controller AddressSearch method with your location string or address segments.
  3. Only use a return address object to set the objectAssignment address!
    Many of our services require valid formatted addresses objectAssignments, not including an address or overwriting parts of an address could lead to errors. If for some reason a valid location will not return an address from our Geo Controller, you can contact our Support team.

Updating objectAssignment

Make sure you follow our Swagger Documentation specs for updating properties of our objectAssignment object. For example: using non-existing values won’t throw errors but will result in data loss of the properties you’re trying to save as they will not be persisted and returned.

A lot of properties have enum values and these can be quite cumbersome to work with depending on what language your app is written in. The easiest way is to include them from a generated client of our API. If this is not an option for your development team then keep in mind that our enums are all string type enums and can be passed as a string (as long as it matches in case).

Save objectAssignment

When saving an objectAssignment always make sure the return value of the request (the updated objectAssignment) updates any local state in your application. Failing to do so could lead to errors and/or loss of data on subsequent saves.

Understanding error messages

From time to time saving an objectAssignment will produce errors, the most common are listed below:

  • Broken business rules
    These errors inform developers/users that there are conflicts in the provided data. This could for instance be missing fields when publishing the objectAssignment or a mismatch between a buildingYear and buildingPeriod property for example.
  • Type error
    These errors are thrown when our API expects a certain type for a value but a other value was provided by your development team.
  • Duplicate key
    This error pops up if you’re trying to save a new objectAssignment with an Id that is already found in the database. This can happen if you forget to update your local state and save the objectAssignment again with the isNew property still set to true.