Attribuutit

Attribuuttiasetukset hallintapaneelissa — Asetukset > Attribuutit ja tunnisteet

Määritelmä

Attribuutit ovat konfiguroitava sarakejärjestelmä, joka on TWICE Commercen jokaisen taulukon ja yksityiskohtanäkymän taustalla. Attribuutteina ilmaiset kaiken sen, mitä liiketoimintasi tarvitsee seurata mutta mikä ei sisälly ydintietomalliin: kuntoluokan, sarjanumeron, takuun alkamispäivän tai mukautetut toimitusohjeet.

Vertaus: Attribuutit toimivat kuten laskentataulukon mukautetut sarakkeet — määrittelet ne kerran, ja ne näkyvät taulukoissa, lomakkeissa, suodattimissa ja vienneissä.

Missä attribuutteja käytetään

Jokainen attribuutti kuuluu täsmälleen yhteen resurssiin:

Resurssi	Koskee
`inventory`	Varastoartikkeleita ja SKU:ita, joihin ne kuuluvat
`catalog`	Listauksia
`customers`	Asiakasprofiileja
`orders`	Tilauksia

Samaa attribuuttia ei voi käyttää useassa resurssissa — jos tarvitset samankaltaiset kentät sekä asiakkaille että tilauksille, määrittelet ne erikseen. Näin kunkin resurssin skeema pysyy selkeänä eikä tietoja vuoda resurssien välillä. Varastoattribuuteilla voi olla toinen kahdesta alkuperästä:

sku — attribuutti määritellään SKU-tasolla, ja jokainen kyseisen SKU:n alla oleva varastoartikkeli perii sen
article — attribuutti määritellään vain varastoartikkelitasolla (varastoartikkeleita kutsutaan sisäisesti myös artikkeleiksi)

Tämän jaon ansiosta voit määritellä esimerkiksi ”Merkki”-kentän kerran SKU:lle ja ”Sarjanumero”-kentän erikseen jokaiselle varastoartikkelille ilman kenttien monistamista.

Attribuuttien tietomuodot

TWICE Commerce tukee kahdeksaa attribuuttimuotoa:

Muoto	Käyttötarkoitus	Tallennusmuoto
`text`	Lyhyet nimikkeet, tunnisteet, muistiinpanot — voidaan rajata syötemaskeilla	Merkkijono
`number`	Mitattavat arvot — paino, mitat, kapasiteetti	Numero
`boolean`	Kyllä / Ei -liput	Totuusarvo
`date`	Kalenteripäivät ilman kellonaikaa	ISO 8601 -päivämäärä
`datetime`	Tarkat aikaleimat	ISO 8601 -aikaleima
`select`	Yksi valinta määritellystä vaihtoehtolistasta	Merkkijono (vaihtoehdon `key`)
`multiselect`	Useita valintoja vaihtoehtolistasta	Merkkijonotaulukko
`formula`	Arvo lasketaan muista attribuuteista ja järjestelmäkentistä	Merkkijonolauseke

Erillistä currency-, percent-, email-, url-, phone-, file-, relation- tai external-muotoa ei ole — käytä number-muotoa valuutta- ja prosenttiarvoille, text-muotoa sähköposteille ja URL-osoitteille sekä dokumentteja tiedostoliitteille. text-attribuutti voi rajata hyväksymäänsä sisältöä syötemaskeilla, jotka kuvaavat kiinteän muodon, kuten kortti- tai lisenssinumeron. Maskit eivät ilmaise avoimia muotoja kuten sähköpostiosoitteita.

Select- ja multiselect-vaihtoehdot

Jokainen select- tai multiselect-attribuutin vaihtoehto on { key, label } -pari:

[
  { "key": "good", "label": "Good" },
  { "key": "fair", "label": "Fair" },
  { "key": "needs-repair", "label": "Needs repair" }
]

key on muuttumaton tunniste, joka tallennetaan tietueille. label on käyttäjille näkyvä teksti, jota voi muokata vapaasti rikkomatta historiatietoja. Molempien enimmäispituus on 255 merkkiä.

Kaava-attribuutit

Kaava-attribuutit laskevat arvonsa saman resurssin muista kentistä. Kukin resurssi tarjoaa kaavoille eri joukon järjestelmäkenttiä:

Resurssi	Kaavoissa käytettävissä olevat järjestelmäkentät
Asiakas	`created_at`, `first_name`, `last_name`, `phone`, `email`, `marketing_consent`, `language`
Inventaario	`created_at`, `name`, `code`, `item_costs`, `item_income`
Katalogi	`created_at`, `name`, `status`, `description`

Tyypillinen kaava käyttää näitä järjestelmäkenttiä sekä muita attribuutteja — esimerkiksi varastoartikkelin kaava item_income - item_costs tuottaa kertyneen tuoton. Kaava lasketaan uudelleen aina, kun sen syötteet muuttuvat. Lue lisää: Kaavat

Syötemaskit

text-attribuutilla voi olla syötemaskeja — mallimerkkijonoja, jotka kuvaavat tarkan muodon, jonka arvo saa ottaa, esimerkiksi 123456 #### ######[#] jäsenkortin numerolle. Arvo, joka ei vastaa mitään attribuutin maskia, hylätään. Jokainen maski ohjaa kolmea asiaa yhtä aikaa: palvelimen soveltamaa tarkistussääntöä, asiakkaalle näkyvää paikkamerkkiä ja muotoilua, jonka kenttä tekee kirjoitettaessa. Ne johdetaan samasta maskista, joten ne eivät voi olla ristiriidassa keskenään. Maskit koskevat vain text-muotoa. Niitä muokataan attribuuttipaneelissa kohdassa Asetukset > Attribuutit ja tunnisteet, jossa osion nimi on Accepted formats ja Read how formats work avaa syntaksiohjeen. Jokainen rivi näyttää täytetyn esimerkin ja hyväksytyn arvon pituuden, joten yhden merkin virhe valinnaisessa lohkossa näkyy ennen tallennusta.

Attribuuttipaneeli, jossa on syötetty maski sekä sen täytetty esimerkki ja hyväksytyn arvon pituus — Asetukset > Attribuutit ja tunnisteet — hyväksyttyjen muotojen editori

Maskin syntaksi

Kaikki maskissa on kiinteää tekstiä, ellei se ole jokin näistä symboleista:

Symboli	Vastaa
`#`	Yhtä numeroa, `0`–`9`
`@`	Yhtä kirjainta missä tahansa aakkostossa — `ä`, `ö`, `å` ja `Ç` kelpaavat kaikki
`*`	Yhtä kirjainta tai numeroa
`{abc}`	Yhtä merkkiä, jonka on oltava jokin luetelluista
`[…]`	Valinnaista loppuosaa, jonka asiakas voi jättää pois — joko kokonaan mukana tai kokonaan poissa
`\`	Tekee seuraavasta merkistä kirjaimellisen, jolloin saa kirjaimellisen merkin `#`, `@`, `*`, `{`, `}`, `[`, `]` tai `\`

Kiinteä teksti vastaa ja näkyy täsmälleen sellaisena kuin sen kirjoitit, välilyönnit ja viivat mukaan lukien. 123456 #### tarkoittaa kuutta kiinteää numeroa, välilyöntiä ja sitten neljää numeropaikkaa — alun numeroita ei koskaan tulkita täytettäviksi paikoiksi. Editori valvoo lisäksi muutamaa sääntöä:

{…} luettelee jäsenensä kirjaimellisesti. Välejä ei ole: {1-3} hyväksyy merkin 1, - tai 3, ei väliä 1–3. Kirjainkoko on tarkka, joten {AB} hylkää merkin a.
Maskissa voi olla enintään yksi valinnainen lohko, ja sen on oltava lopussa.
Maskissa on oltava vähintään yksi syöttöpaikka — #, @, * tai {…}.
Merkkijoukko ei voi olla tyhjä, sisäkkäinen tai sisältää samaa merkkiä kahdesti.

How formats work -ikkuna, jossa luetellaan maskin symbolit ja esimerkit — Read how formats work — sovelluksen sisäinen syntaksiohje

Esimerkkejä, mukana arvon pituus, jonka editori ilmoittaa kunkin maskin vieressä:

Maski	Hyväksyy	Pituus
`####`	`1234`	4
`@@-####`	`AB-1234`	6
`CARD-####`	`CARD-1234`	8
`{ABC}-###`	`A-123`, `C-456`	4
`123456 #### ######[#]`	`123456 1140 411905`, `123456 1140 4119051`	16–17
`#####[-####]`	`12345`, `12345-6789`	5–9

Pituus lasketaan arvosta sellaisena kuin se luetaan kortilta — kiinteät merkit mukaan lukien, erottimet pois lukien — ei asiakkaan kirjoittamien merkkien määrästä.

Useita hyväksyttyjä muotoja

Attribuutti voi hyväksyä useita muotoja. Lisää yksi maski muotoa kohti, enintään 10 maskia, kukin enintään 100 merkkiä. Listan maskien on oltava erotettavissa toisistaan kiinteiden alkujensa perusteella, kun erottimet on poistettu. TWICE hylkää listan, jossa yhden maskin kiinteä alku on toisen alun etuliite: 123456 #### ja 998877 #### käyvät, @@@-### ja @@@### eivät, koska kummallakaan ei ole erottavaa kiinteää alkua. Virheilmoitus nimeää kaksi ristiriitaista maskia. Kentän toiminta riippuu siitä, montako maskia attribuutilla on:

Maskeja	Toiminta
Yksi	Kiinteä alku täytetään asiakkaalle valmiiksi, kun hän siirtyy kenttään, jolloin hän kirjoittaa vain oman osuutensa. Se tyhjenee jälleen, jos hän poistuu kirjoittamatta. Paikkamerkki näyttää tämän yhden muodon.
Useita	Mitään ei täytetä valmiiksi — ensimmäinen kirjoitettu merkki valitsee maskin, ja kenttä muotoilee siitä eteenpäin. Paikkamerkki luettelee kaikki hyväksytyt muodot.

Arvo, joka ei vastaa mitään maskia, jätetään asiakkaan kirjoittaessa vapaaksi tekstiksi sen sijaan, että se pakotettaisiin lähimpään muotoon. Lähetettäessä se hylätään.

Missä maskeja valvotaan

Maskit eivät koskaan tee kentästä pakollista. Tyhjä arvo menee aina läpi — läsnäoloa ohjataan erikseen kentän Required-asetuksella.

Verkkokaupan kassa — attribuuttiin sidotut kentät Yhteystiedot-vaiheessa ja Lisätiedot-vaiheessa muotoilevat arvon asiakkaan kirjoittaessa, täyttävät kiinteän alun ja normalisoivat ilman erottimia liitetyn arvon. Virheellinen arvo estää vaiheen.
Hallintapaneeli — sama maskattu syöttö on käytössä kaikkialla, missä henkilökunta syöttää attribuuttiarvoja, mukaan lukien asiakaspaneeli ja uuden tilauksen kassakentät.
API ja palvelin — jokainen text-attribuutin arvon kirjoitus tarkistetaan. Vastaus on 400, joka nimeää attribuutin ja täytetyn esimerkin jokaisesta hyväksytystä maskista: Member card: must match the format 123456 1234 567890. Kassan vahvistuksessa palvelin tarkistaa yhteystietoattribuutit uudelleen ja raportoi virheelliset arvot erillään puuttuvista pakollisista.

Arvot vertaillaan näyttömuodossaan, kiinteät merkit mukaan lukien. Lähetä "123456 1140 411905", ei "1234561140411905" — verkkokaupan syöttökenttä normalisoi liitetyt arvot, API ei.

Verkkokaupan kassan Yhteystiedot-vaihe, jossa maskattu Jäsenkortti-kenttä näyttää täytetyn kiinteän alun ja muotoillut kirjoitetut numerot — Maskattu attribuuttikenttä kassalla kesken syötön

Maskien muuttaminen

Maskit kuuluvat text-muotoon. Attribuutin muodon vaihtaminen joksikin muuksi tyhjentää ne.
Maskin lisääminen tai muokkaaminen tarkistaa siitä eteenpäin kirjoitettavat arvot. Jo tallennettuja arvoja ei kosketa eikä tarkisteta uudelleen.
Kaikkien maskien poistaminen jättää kentän jälleen rajoittamattomaksi.

Keskeiset ominaisuudet

Attribuuttimääritys sisältää:

Ominaisuus	Tyyppi	Kuvaus
`id`	UUID	Pysyvä tunniste
`key`	String	Koneluettava tunniste, jota käytetään API:ssa ja vienneissä
`name`	String	Näyttönimi (esim. ”Kunto”)
`description`	String	Valinnainen ohjeteksti, joka näkyy lomakkeissa
`format`	Enum	Yksi yllä olevista kahdeksasta muodosta
`valueOptions`	Array	`{ key, label }` -parit select-/multiselect-muodoille; muuten `null`
`formula`	String	Kaava-attribuuttien lauseke
`resource`	Enum	`inventory`, `catalog`, `customers`, `orders`
`groupId`	UUID	Valinnainen attribuuttiryhmä, johon attribuutti kuuluu
`systemGroup`	Enum	`system` (asiakas) järjestelmän hallinnoimille ryhmille
`sortOrder`	Number	Sijainti ryhmän sisällä
`global`	Boolean	Onko attribuutti järjestelmän määrittelemä (true) vai vuokralaisen määrittelemä (false)

Järjestelmäryhmät ovat varattuja kategorioita — system asiakkaille — jotka sisältävät TWICE Commercen puolestasi hallinnoimat attribuutit.

Periytyminen: SKU > varastoartikkeli

Erityisesti varastoattribuuteille pätee:

Attribuutti, jonka alkuperä on origin: sku, määritellään SKU:lle, ja se luetaan jokaiselta kyseiseen SKU:hun kuuluvalta varastoartikkelilta
Attribuutti, jonka alkuperä on origin: article, määritellään suoraan varastoartikkelille eikä sitä jaeta muiden kanssa
SKU-alkuperäistä attribuuttia ei voi muokata yksittäisellä varastoartikkelilla — muokkaat sitä SKU:lla, ja muutos leviää kaikille artikkeleille

SKU:n attribuutit toimivat siis varastoartikkeliensa ”mallipohjana”, ja kukin varastoartikkeli tallentaa vain yksikkökohtaisesti vaihtelevat arvot (sarjanumero, kunto, sijainti, ostopäivä).

Tilausattribuutit

orders-resurssiin kuuluvat attribuutit liittävät mukautettua tietoa yksittäisiin tilauksiin varasto-, katalogi- tai asiakastietueiden sijaan. Yleisiä esimerkkejä: kustannuspaikka, lahjaviesti, ostotilausnumero tai erityiset toimitusohjeet.

Kerääminen kassalla

Lisää attribuuttikenttä kassan yhteystietolomakkeeseen ja sido se attribuuttiin. Kassalla järjestelmä ohjaa kerätyn arvon attribuutin resurssin mukaan:

orders — tallennetaan tilauksen attribuuttiarvoihin
customers — tallennetaan asiakasprofiiliin

Sama kassalomake voi siis kerätä sekä tilauskohtaista että asiakasprofiilin tietoa yhdessä vaiheessa.

Vahvistussähköposti

Kerätyt tilausattribuuttien arvot näkyvät automaattisesti tilausvahvistussähköpostissa:

Globaalit tilausattribuutit näkyvät aina — viivalla (—) merkittynä, jos arvoa ei kerätty
Ei-globaalit tilausattribuutit näkyvät vain, kun arvo on olemassa

Arvot muotoillaan vuokralaisen maa-asetusten mukaan: päivämäärät käyttävät määrittämääsi päivämäärämuotoa, select-attribuutit näyttävät vaihtoehdon nimikkeen, totuusarvot näkyvät muodossa Kyllä/Ei ja multiselect-arvot erotellaan pilkuilla.

Hallintapaneeli

Tilausattribuuttien arvot näkyvät tilauksen tietosivulla omalla attribuuttikortillaan. Voit lisätä, muokata ja poistaa arvoja suoraan. Tilausattribuutit näkyvät myös suodatettavina ja lajiteltavina sarakkeina tilaustaulukossa.

Suodatus ja haku

Kun attribuutti on olemassa, se ilmestyy automaattisesti resurssinsa taulukkoon:

Toiminto	Tarkennus
Sarake	Uusi sarake resurssin taulukossa, oletuksena piilotettu — näytä sarakeasetuksista
Suodatin	Suodatinoperaattori riippuu muodosta — `equals`, `contains`, `is any of`, `before`, `after`, `is null` jne.
Lajittelu	Kaikki muodot kaavaa lukuun ottamatta ovat lajiteltavissa
Ryhmittely	Boolean-, select- ja päivämääräattribuutit ryhmittelevät taulukon rivejä
Haku	Teksti- ja numeroattribuutit löytyvät työkalupalkin haulla
Vienti	Näkyvät attribuuttisarakkeet sisältyvät CSV-vientiin

Haku on kokotekstihaku ja kohdistuu kaikkiin merkkijonoksi muunnettaviin attribuuttiarvoihin — työkalupalkin haku löytää osumat myös piilotetuista sarakkeista.

API-käyttö

Attribuutit sisältyvät jokaiseen API-vastaukseen sillä resurssilla, jota ne koskevat. Ne on avainnettu id-kentällä ja esitetään tyypitettynä arvotietueena. Tyypillinen varastovastaus sisältää:

{
  "id": "stk_abc123",
  "skuId": "sku_xyz789",
  "attributes": {
    "attr_color": "Navy",
    "attr_condition": "good",
    "attr_serialNumber": "BK-2024-0011",
    "attr_purchasePrice": 89.00
  }
}

Select-attribuuttien arvot ovat vaihtoehdon key, eivät käyttäjälle näkyvä label.

Elinkaari

Luominen

Avaa Asetukset > Attribuutit ja tunnisteet
Valitse resurssi, jota attribuutti koskee (varasto, katalogi, asiakas, tilaus)
Määritä nimi, kuvaus ja muoto
select- / multiselect-muodoille määritä vaihtoehtolista
formula-muodolle kirjoita lauseke ja valitse tuloksen muoto
Halutessasi liitä ryhmään ja määritä lajittelujärjestys

Päivittäminen

Nimeä, kuvausta, lajittelujärjestystä ja ryhmää voi muuttaa vapaasti
Vaihtoehtojen lisääminen select-/multiselect-listaan on turvallista
Vaihtoehtojen label-tekstien uudelleennimeäminen on turvallista — tallennettuna säilyy key
Vaihtoehdon poistaminen rikkoo kaikki siihen viitanneet tietueet — TWICE Commerce varoittaa ennen poistoa
Muodon vaihtaminen on rajoitettua, koska muunnos voi hävittää tietoa; turvallisempi tapa on luoda uusi attribuutti ja siirtää arvot

Arkistointi ja poistaminen

Arkistointi piilottaa attribuutin uusilta syötöiltä mutta säilyttää historiatiedot
Poistaminen poistaa attribuuttimäärityksen ja kaikki sen tallennetut arvot jokaisesta tietueesta; tätä ei voi perua
Käytä arkistointia lähes aina; poistaminen on tarkoitettu vain vahingossa luotujen attribuuttien siivoamiseen

Suhteet

Usein kysytyt kysymykset

Voinko käyttää samaa attribuuttia varastoartikkeleilla ja listauksilla?

Et — jokainen attribuutti kuuluu yhteen resurssiin. Luo vastaavat attribuutit kummallekin resurssille, jos tarvitset rinnakkaiset kentät.

Mikä ero on SKU-alkuperäisillä ja varastoartikkeli-alkuperäisillä attribuuteilla?

SKU-alkuperäiset attribuutit määritellään kerran SKU:lle ja luetaan jokaiselta sen alla olevalta varastoartikkelilta (esim. merkki). Varastoartikkeli-alkuperäiset attribuutit ovat yksilöllisiä yhdelle fyysiselle yksikölle (esim. sarjanumero). Valitse alkuperä sen mukaan, vaihteleeko arvo yksiköittäin.

Voinko muuttaa select-attribuutin vaihtoehtoja käyttöönoton jälkeen?

Vaihtoehtojen lisääminen on turvallista. Vaihtoehdon käyttäjälle näkyvän label-tekstin uudelleennimeäminen on turvallista — taustalla oleva key säilyy. Vaihtoehdon poistaminen rikkoo kaikki siihen viitanneet tietueet, joten TWICE Commerce varoittaa ennen poistoa.

Miten kaava-attribuutit päivittyvät?

Kaavat lasketaan uudelleen aina, kun niiden syötekentät muuttuvat — manuaalista päivitystä ei tarvita. Tulos on vain luettavissa.

Näkyvätkö attribuutit asiakkaille?

Oletuksena eivät. Attribuutin näkyminen verkkokaupassa riippuu verkkokaupan teeman asetuksista — teemat valitsevat, mitkä attribuutit ne näyttävät listaussivuilla.

Voinko muokata attribuutteja massana?

Kyllä. Valitse rivit missä tahansa taulukossa, valitse Bulk edit ja aseta uudet arvot mille tahansa näkyvälle attribuuttisarakkeelle.

Kehittäjän viite

Attribuutit esitetään API:ssa nimellä attributes.

API: Attributes

Avaa rajapinta API-viitteessä.

Aiheeseen liittyvää

Attribuuttiryhmät

Ryhmittele toisiinsa liittyvät attribuutit selkeämpiä lomakkeita varten

Kaavat

Kirjoita lausekkeita laskettaville attribuuteille

Kategoriataksonomia

Kategoriat ehdottavat attribuutteja — ne toimivat yhdessä

Taulukot

Missä attribuutit näkyvät suodatettavina sarakkeina

Tervetuloa TWICE-dokumentaatioon

Liikkuminen TWICEssä

Järjestelmän ymmärtäminen

Määritelmä

Missä attribuutteja käytetään