Stel aangepaste veldwaarden in

Werk aangepaste veldwaarden bij op records met type-specifieke parameters voor elk veldtype

Stel aangepaste veldwaarden in

Aangepaste velden breiden de standaard recordstructuur van Blue uit met bedrijfsspecifieke gegevens. Deze endpoint stelt je in staat om waarden in te stellen of bij te werken voor elk aangepast veld op een record. Elk veldtype vereist specifieke parameters om de gegevensintegriteit en juiste validatie te waarborgen.

Basisvoorbeeld

mutation SetTextFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_xyz789"
    text: "Project specification document"
  })
}

Geavanceerd voorbeeld

mutation SetMultipleFieldTypes {
  # Set a date range field
  dateField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_date_001"
    startDate: "2024-01-15T09:00:00Z"
    endDate: "2024-01-31T17:00:00Z"
    timezone: "America/New_York"
  })
  
  # Set a multi-select field
  selectField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_select_002"
    customFieldOptionIds: ["option_high", "option_urgent", "option_client"]
  })
  
  # Set a location field
  locationField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_location_003"
    latitude: 40.7128
    longitude: -74.0060
  })
}

Invoervelden

SetTodoCustomFieldInput

Parameter	Type	Vereist	Beschrijving
`todoId`	String!	✅ Ja	De ID van het record dat moet worden bijgewerkt
`customFieldId`	String!	✅ Ja	De ID van het aangepaste veld
`text`	String	Nee	Voor TEXT_SINGLE, TEXT_MULTI, TELEFOON, E-MAIL, URL
`number`	Float	Nee	Voor NUMMER, PERCENTAGE, BEOORDELING
`currency`	String	Nee	Valutacode voor CURRENCY-type (bijv. "USD")
`checked`	Boolean	Nee	Voor CHECKBOX-velden
`startDate`	DateTime	Nee	Startdatum voor DATUM-velden
`endDate`	DateTime	Nee	Einddatum voor DATUM bereikvelden
`timezone`	String	Nee	Tijdzone voor DATUM-velden (bijv. "America/New_York")
`latitude`	Float	Nee	Breedtegraad voor LOCATIE-velden
`longitude`	Float	Nee	Lengtegraad voor LOCATIE-velden
`regionCode`	String	Nee	Regiocode voor TELEFOON-velden
`countryCodes`	[String!]	Nee	ISO-landcodes voor LAND-velden
`customFieldOptionId`	String	Nee	Optie-ID voor SELECT_SINGLE-velden
`customFieldOptionIds`	[String!]	Nee	Optie-ID's voor SELECT_MULTI-velden
`customFieldReferenceTodoIds`	[String!]	Nee	Record-ID's voor REFERENTIE-velden

Voorbeelden van veldtypes

Tekstvelden

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_description"
    text: "Detailed project requirements and specifications"
  })
}

Nummervelden

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_budget"
    number: 15000.50
  })
}

Selectvelden

# Single Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_priority"
    customFieldOptionId: "option_high"
  })
}

# Multi Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_tags"
    customFieldOptionIds: ["option_frontend", "option_urgent", "option_v2"]
  })
}

Datumvelden

# Single Date
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_deadline"
    startDate: "2024-12-31T23:59:59Z"
  })
}

# Date Range
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_project_timeline"
    startDate: "2024-01-01T00:00:00Z"
    endDate: "2024-03-31T23:59:59Z"
    timezone: "UTC"
  })
}

Locatievelden

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_office_location"
    latitude: 37.7749
    longitude: -122.4194
  })
}

Valuta-velden

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_invoice_amount"
    number: 5000
    currency: "USD"
  })
}

Bestandsvelden

Bestandsvelden gebruiken aparte mutaties:

# Add a file
mutation {
  createTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

# Remove a file
mutation {
  deleteTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

Waarden instellen tijdens het maken van een record

Je kunt aangepaste veldwaarden instellen bij het maken van een nieuw record:

mutation {
  createTodo(input: {
    todoListId: "list_project_123"
    title: "New Feature Development"
    customFields: [
      {
        customFieldId: "field_priority"
        value: "high"
      },
      {
        customFieldId: "field_estimate"
        value: "8"
      }
    ]
  }) {
    id
    customFields {
      customField {
        name
      }
      value
    }
  }
}

Responsvelden

De mutatie retourneert een boolean die aangeeft of de bewerking is geslaagd:

Veld	Type	Beschrijving
`setTodoCustomField`	Boolean!	Waar als de bewerking is geslaagd

Vereiste machtigingen

Gebruikers moeten toestemming hebben om zowel het record als het specifieke aangepaste veld te bewerken:

Rol	Kan veldwaarden instellen
`OWNER`	✅ Ja
`ADMIN`	✅ Ja
`MEMBER`	✅ Ja (tenzij beperkt door aangepaste rol)
`CLIENT`	✅ Ja (tenzij beperkt door aangepaste rol)

Voor gebruikers met aangepaste projectrollen voert het systeem een controle in twee lagen uit:

Eerst wordt gecontroleerd of de gebruiker toegang heeft op projectniveau
Vervolgens wordt gecontroleerd of het specifieke veld is gemarkeerd als editable in hun configuratie voor aangepaste rollen

Dit betekent dat een gebruiker mogelijk algemene projecttoegang heeft, maar nog steeds beperkt kan zijn in het bewerken van bepaalde velden op basis van hun aangepaste rol.

Foutreacties

Aangepast veld niet gevonden

{
  "errors": [{
    "message": "Custom field was not found.",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Ongeautoriseerde toegang

{
  "errors": [{
    "message": "You are not authorized.",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

Ongeldige veldwaarde

{
  "errors": [{
    "message": "Invalid value for field type NUMBER",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Belangrijke notities

Upsert-gedrag: De mutatie maakt een nieuwe veldwaarde aan als deze nog niet bestaat, of werkt de bestaande waarde bij
Typeveiligheid: Geef alleen parameters op die overeenkomen met het veldtype (bijv. stuur geen text voor een NUMMER-veld)
Bijwerkingen: Het instellen van waarden activeert:
- Herberekeningen van formulevelden
- Automatiseringsregels
- Webhookmeldingen
- Activiteitenlogboekvermeldingen
- Grafiekupdates
Speciale gedragingen:
- CURRENCY-velden verwerken automatisch conversieberekeningen
- REFERENCE-velden werken bi-directionele relaties bij
- FORMULA-velden zijn alleen-lezen en kunnen niet direct worden ingesteld (ze worden automatisch berekend)
- LOOKUP-velden zijn alleen-lezen en kunnen niet direct worden ingesteld (ze halen gegevens uit verwezen records)
- BUTTON-velden activeren automatiseringsevents wanneer ze "worden aangeklikt"
Validatie: De API valideert dat:
- Het record bestaat in het project
- Het aangepaste veld bestaat in hetzelfde project
- De gebruiker heeft bewerkingsrechten
- De waarde voldoet aan de vereisten van het veldtype

Waardeformaatreferentie

Veldtype	Parameter	Formaat	Voorbeeld
`TEXT_SINGLE`	`text`	String	`"Project Alpha"`
`TEXT_MULTI`	`text`	String with newlines	`"Line 1\nLine 2"`
`NUMBER`	`number`	Float	`42.5`
`CURRENCY`	`number` + `currency`	Float + ISO code	`1000.00` + `"USD"`
`PERCENT`	`number`	Float (0-100)	`75`
`RATING`	`number`	Float (within min/max)	`4.5`
`CHECKBOX`	`checked`	Boolean	`true`
`DATE`	`startDate`	ISO 8601 DateTime	`"2024-01-15T00:00:00Z"`
`DATE` (range)	`startDate` + `endDate`	ISO 8601 DateTimes	See example above
`SELECT_SINGLE`	`customFieldOptionId`	Option ID	`"option_123"`
`SELECT_MULTI`	`customFieldOptionIds`	Array of Option IDs	`["opt_1", "opt_2"]`
`PHONE`	`text`	String	`"+1-555-123-4567"`
`EMAIL`	`text`	String	`"user@example.com"`
`URL`	`text`	String	`"https://example.com"`
`LOCATION`	`latitude` + `longitude`	Floats	`40.7128, -74.0060`
`COUNTRY`	`countryCodes`	ISO 3166 codes	`["US", "CA"]`
`REFERENCE`	`customFieldReferenceTodoIds`	Array of record IDs	`["todo_1", "todo_2"]`
`FORMULA`	N/A	Read-only - calculated automatically	N/A
`LOOKUP`	N/A	Read-only - pulls from references	N/A

Gerelateerde eindpunten

Lijst met aangepaste velden - Verkrijg beschikbare aangepaste velden
Maak aangepast veld aan - Voeg nieuwe aangepaste velden toe
Haal recorddetails op - Haal records op met aangepaste veldwaarden
Bulkupdate records - Werk meerdere records tegelijk bij