Ställ in anpassade fältvärden

Uppdatera anpassade fältvärden på poster med typ-specifika parametrar för varje fälttyp

Ställ in anpassade fältvärden

Anpassade fält utökar Blues standardpoststruktur med affärsspecifika data. Denna slutpunkt gör det möjligt för dig att ställa in eller uppdatera värden för vilket anpassat fält som helst på en post. Varje fälttyp kräver specifika parametrar för att säkerställa dataintegritet och korrekt validering.

Grundläggande exempel

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

Avancerat exempel

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
  })
}

Indata parametrar

SetTodoCustomFieldInput

Parameter	Typ	Obligatorisk	Beskrivning
`todoId`	String!	✅ Ja	ID för posten som ska uppdateras
`customFieldId`	String!	✅ Ja	ID för det anpassade fältet
`text`	String	Nej	För TEXT_SINGLE, TEXT_MULTI, TELEFON, EMAIL, URL
`number`	Float	Nej	För NUMMER, PROCENT, BETYG
`currency`	String	Nej	Valuta kod för CURRENCY typ (t.ex. "USD")
`checked`	Boolean	Nej	För CHECKBOX fält
`startDate`	DateTime	Nej	Startdatum för DATE fält
`endDate`	DateTime	Nej	Slutdatum för DATE intervallfält
`timezone`	String	Nej	Tidszon för DATE fält (t.ex. "America/New_York")
`latitude`	Float	Nej	Breddgrad för LOCATION fält
`longitude`	Float	Nej	Längdgrad för LOCATION fält
`regionCode`	String	Nej	Regionskod för TELEFON fält
`countryCodes`	[String!]	Nej	ISO landskoder för COUNTRY fält
`customFieldOptionId`	String	Nej	Alternativ ID för SELECT_SINGLE fält
`customFieldOptionIds`	[String!]	Nej	Alternativ ID för SELECT_MULTI fält
`customFieldReferenceTodoIds`	[String!]	Nej	Post-ID för REFERENCE fält

Exempel på fälttyper

Textfält

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

Nummerfält

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

Väljfält

# 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"]
  })
}

Datumfält

# 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"
  })
}

Platsfält

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

Valutafält

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

Filfält

Filfält använder separata mutationer:

# 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"
  })
}

Ställa in värden vid postskapande

Du kan ställa in anpassade fältvärden när du skapar en ny post:

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
    }
  }
}

Svarsfält

Mutationen returnerar en boolean som indikerar framgång:

Fält	Typ	Beskrivning
`setTodoCustomField`	Boolean!	Sant om operationen lyckades

Obligatoriska behörigheter

Användare måste ha behörighet att redigera både posten och det specifika anpassade fältet:

Roll	Kan ställa in fältvärden
`OWNER`	✅ Ja
`ADMIN`	✅ Ja
`MEMBER`	✅ Ja (om det inte är begränsat av anpassad roll)
`CLIENT`	✅ Ja (om det inte är begränsat av anpassad roll)

För användare med anpassade projektroller utför systemet en tvåstegs kontroll:

Först verifierar det att användaren har projekt-nivå åtkomst
Sedan kontrollerar det om det specifika fältet är markerat som editable i deras konfiguration för anpassad roll

Detta innebär att en användare kan ha allmän projektåtkomst men fortfarande vara begränsad från att redigera vissa fält baserat på deras anpassade roll.

Felmeddelanden

Anpassat fält hittades inte

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

Obefogad åtkomst

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

Ogiltigt fältvärde

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

Viktiga anteckningar

Upsert-beteende: Mutationen skapar ett nytt fältvärde om inget finns, eller uppdaterar det befintliga värdet
Typ-säkerhet: Ge endast parametrar som matchar fälttypen (t.ex. skicka inte text för ett NUMMER fält)
Bieffekter: Att ställa in värden utlöser:
- Beräkningar av formelfält
- Automatiseringsregler
- Webhook-notifikationer
- Aktivitetsloggposter
- Diagramuppdateringar
Speciella beteenden:
- CURRENCY fält hanterar automatiskt konverteringsberäkningar
- REFERENCE fält uppdaterar bi-riktade relationer
- FORMULA fält är skrivskyddade och kan inte ställas in direkt (de beräknas automatiskt)
- LOOKUP fält är skrivskyddade och kan inte ställas in direkt (de hämtar data från refererade poster)
- BUTTON fält utlöser automatiseringsevenemang när de "klickas"
Validering: API:et validerar att:
- Posten finns i projektet
- Det anpassade fältet finns i samma projekt
- Användaren har redigeringsbehörigheter
- Värdet matchar fälttypens krav

Referens för värdformat

Fälttyp	Parameter	Format	Exempel
`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

Relaterade slutpunkter

Lista anpassade fält - Hämta tillgängliga anpassade fält
Skapa anpassat fält - Lägg till nya anpassade fält
Hämta postdetaljer - Hämta poster med anpassade fältvärden
Bulkuppdatera poster - Uppdatera flera poster på en gång