Custom Fields & Mappings

Import a provider's field catalogue, then optionally map compatible provider fields onto Alution's native fields. Unmapped provider fields remain available as provider-grouped additional data.

How the field system works

The import endpoint accepts one JSON Schema document, but it stores and returns a collection of field records—one record per property. A field resource has id, group, name, type, description, and rules; it does not return the original schema document.

group is the provider namespace and type is the singular related model alias. The same system is used when provider-specific fields are exchanged on supported resources, including contacts, addresses, users, projects, and tickets. Keep external record identifier values independent from the field group.

List fields

Required scope: custom-fields:read. Filter with optional group and type query parameters. type is normalized to singular form.

Import fields

Required scope: custom-fields:write. Send group, related model type, and schema.

{
  "group": "ExampleErp",
  "type": "contact",
  "schema": {
    "type": "object",
    "properties": {
      "customer_number": {
        "type": "string",
        "description": "Customer number in the ERP"
      },
      "credit_limit": { "type": "number" }
    },
    "required": ["customer_number"]
  }
}

The response is a collection resembling:

[
  {
    "id": 41,
    "group": "ExampleErp",
    "name": "customer_number",
    "type": "string",
    "description": "Customer number in the ERP",
    "rules": ["required", "string"]
  }
]

Get one field

Returns a single stored field record. Required scope: custom-fields:read.

Get mappings

Both group and type are required. The response contains force_update, fields (an array of provider field-name strings), and overridable (a map of Alution target field names to required compatible types).

{
  "force_update": false,
  "fields": ["customer_number", "credit_limit"],
  "overridable": { "name": "string", "description": "string" }
}

Update mappings

Required scope: custom-fields:write. Both query parameters are mandatory. In mappings, each key is an Alution target and each value is a field from the provider schema. The server rejects unknown targets, missing provider fields, and incompatible types.

{
  "mappings": {
    "name": "company_name",
    "description": "customer_note"
  }
}