Inserting data

For cloud customers on Azure, the possibility to insert and update data with the REST API is now available. PUT, PATCH and POST methods have been added to support this.

Method	Description
PUT	Insert or update a specific resource by specifying the identifier
POST	Insert a new record without specifying the identifier (only available for resources that use an autokey value for the identifier)
PATCH	Update a single property of a specific resource by specifying the identifier

Request body

The body of a request contains the properties that need to be inserted or updated. The request body must be in a JSON format with at least one property.

The API key must be authorized for all the properties specified in the body.

1. For properties that are defined in the API key but not specified in the body the update will be done with default or null values for the PUT method. These properties will NOT be affected by the PATCH method.

2. The properties that are NOT defined in the API key will not be affected by the request.

3. The response body will always return all properties that are linked to the API Key, no matter what method is used.

Properties that are mandatory in the request body for PUT and POST methods:

• Context

• Status

Properties that can be set for an insert but cannot be updated:

• Context

• Currency: If this is not specified in the request, then the currency of the API key’s company will be set.

Properties that are not allowed in the request body:

• Identifier: this should be used in the resource path for the PUT method.

• SystemCompany: this is set in the API key and cannot be manually updated.

• Read-only properties: these kinds of properties are calculated or generated from the database, and cannot be changed by the end user.

Example of a PUT request

PUT https://customer.ultimo.net/api/v1/object/Equipment('00001')

{
  "Context": 1,
  "Description": "Asset",
  "InstallDate": "2022-04-07",
  "NextPmMaintenanceDate": "2023-04-07",
  "Status": 2,
  "CostCenter": "01",
  "Department": "01",
}

Example of a PUT response

{
  "Id": "00001",
  "Context": 1,
  "Description": "Asset",
  "InstallDate": "2022-04-07",
  "NextPmMaintenanceDate": "2023-04-07",
  "Status": 2,
  "CostCenter": "01",
  "Department": "01",
}

Example of a POST request

POST https://customer.ultimo.net/api/v1/object/Equipment

{
  "Context": 1,
  "Description": "Asset",
  "InstallDate": "2022-04-07",
  "NextPmMaintenanceDate": "2023-04-07",
  "Status": 2,
  "CostCenter": "01",
  "Department": "01",
}

Example of a POST response

{
  "Id": "39938",
  "Context": 1,
  "Description": "Asset",
  "InstallDate": "2022-04-07",
  "NextPmMaintenanceDate": "2023-04-07",
  "Status": 2,
  "CostCenter": "01",
  "Department": "01",
}

Example of a PATCH request

PATCH https://customer.ultimo.net/api/v1/object/Equipment('00001')

{
  "Description": "Installation",
}

Example of a PATCH response

{
  "Id": "00001",
  "Context": 1,
  "Description": "Installation",
  "InstallDate": "2022-04-07",
  "NextPmMaintenanceDate": "2023-04-07",
  "Status": 2,
  "CostCenter": "01",
  "Department": "01",
}

Resource paths

The next examples explain the different uses of resource paths for the PUT, PATCH and POST methods:

• Request for a single entity:

  PUT https://customer.ultimo.net/api/v1/object/Equipment('00001')

  PATCH https://customer.ultimo.net/api/v1/object/Equipment('00001')

  POST https://customer.ultimo.net/api/v1/object/Equipment

• Request for single custom entity:

  PUT https://customer.ultimo.net/apa i/v1/object/_Entity('01')

  PATCH https://customer.ultimo.net/api/v1/object/_Entity('01')

  POST https://customer.ultimo.net/api/v1/object/_Entity

• Request for single entity with a composite key by using multiple key properties:

  PUT https://customer.ultimo.net/api/v1/object/BuildingFloor(Building='0001',BuildingPart='001',Id='CODE01')

  PATCH https://customer.ultimo.net/api/v1/object/BuildingFloor(Building='0001',BuildingPart='001',Id='1-0')

• Request for single entity with multiple key properties that includes a navigation property of the related entity the key properties can be omitted:

  PUT https://customer.ultimo.net/api/v1/object/Building('0001')/BuildingParts(Building='0001',Id='001')/BuildingFloors(Building='0001',BuildingPart='001',Id='CODE01')

  PATCH https://customer.ultimo.net/api/v1/object/Building('0001')/BuildingParts(Building='0001',Id='001')/BuildingFloors(Building='0001',BuildingPart='001',Id='1-0')

• The previous example can be shortened to:

  PUT https://customer.ultimo.net/api/v1/object/Building('0001')/BuildingParts('001')/BuildingFloors('CODE01')

  PATCH https://customer.ultimo.net/api/v1/object/Building('0001')/BuildingParts('001')/BuildingFloors('1-0')

  POST https://customer.ultimo.net/api/v1/object/Invoice('00001')/Lines

Navigation properties

‌It is possible to insert an entity by following a navigation property from a single entity to a collection of entities. This is only available for the POST method. Example:

POST https://customer.ultimo.net/api/v1/object/Department('01')/Jobs

It is NOT possible to insert or update an entity by following a navigation property from a single entity to another single entity. Examples:

PUT https://customer.ultimo.net/api/v1/object/Equipment('00001')/Department('01')

POST https://customer.ultimo.net/api/v1/object/Equipment('00001')/Department

PATCH https://customer.ultimo.net/api/v1/object/Equipment('00001')/Department('01')

It is also NOT possible to insert or update an entity by following a navigation property from a single entity to a collection of entities using the PUT method. Examples:

PUT https://customer.ultimo.net/api/v1/object/Department('01')/Jobs('001')

External identifiers

It is possible to insert or update data using an external identifier in the resource path. The external identifier of a resource will be stored in the Ultimo ExternalId property. The combination of ExternalId and DataProvider is unique in Ultimo. Based on this, the record will be identified. When inserting data using REST, the DataProvider is set with the value “Rest” by default, unless stated otherwise on the API key definition in Ultimo.

The next examples explain the different uses of resource paths for the PUT, PATCH, and POST methods using the external identifier:

• Request for a single entity: PUT https://customer.ultimo.net/api/v1/object/Equipment(ExternalId='00001') PATCH https://customer.ultimo.net/api/v1/object/Equipment(ExternalId='00001')

• Request for single entity with a composite key: PUT (UPDATE ONLY) https://customer.ultimo.net/api/v1/object/InvoiceLine(ExternalId='01') PATCH https://customer.ultimo.net/api/v1/object/InvoiceLine(ExternalId='01')

It is NOT possible to use the external identifier when the URL contains a nested path with at least two ExternalId usages or with a combination of the Ultimo Id and an external Id. Examples of bad requests:

PUT https://customer.ultimo.net/api/v1/object/Department(ExternalId='01')/Jobs(ExternalId='002')/Equipments PUT https://customer.ultimo.net/api/v1/object/Department(ExternalId='01')/Jobs('0002')/Equipments

It is NOT possible to insert a resource with a composite key using only the external identifier:

PUT https://customer.ultimo.net/api/v1/object/InvoiceLine(ExternalId='01')

When external identifiers have been used to insert records, it is possible to refer to these records using ExternalId in the request body when inserting and updating other entities.

Example of a request body using ExternalId for reference properties:

{ 
    "Context": 1, 
    "Status": 1, 
    "Description": "Asset", 
    "Vendor.ExternalId": "ExtVendorCode" 
} 

It is NOT possible to use both the Ultimo Id and ExternalId in the request body for the same property.

{ 
    "Vendor.Id": "0001", 
    "Vendor.ExternalId": "ExtVendorCode" 
} 

It is NOT possible to use ExternalId in the request body with reference properties more than one level deep:

{ 
    "Department.Site.ExternalId": "ExtSiteCode" 
} 

Multi-lingual properties

When the API key is set to use multi-lingual properties, it is possible to update all languages (available in the environment) within a request. The languages that are not specified in the request will not be modified.

Example of a request body with a multi-lingual properties:

{ 
    "Description": { 
        "NL": "NL value", 
        "EN": "EN value", 
        "DE": "DE value", 
        "FR": "FR value", 
        "IT": "IT value", 
        "ES": "ES value", 
        "PL": "PL value", 
        "TR": "TR value" 
    } 
} 

When the API key is NOT set to use multi-lingual properties, then it is only possible to update a single language of a multi-lingual property. To do so, it is mandatory to specify for which language the update should be made. You can specify the language using the ‘Content-Language’ request header (case sensitive) in the following format:

• Content-Language: NL

• Content-Language: en-US

Example of a request body without multi-lingual properties:

{ 
    "Description": "NL value" 
}