Create a taxonomy

What you’ll learn

• Key terms used in reference to a Marketplacer Taxonomy
• The high-level schema of the primary taxonomy entities
• The queries and mutations that you can use to create a taxonomy

Key Terms

Example

To further illustrate the concepts described earlier, observe the following Option Type and Value configuration:

Here we have:

• 6 Option Types
  • 3 at the Advert level
  • 3 at the Variant level
• The Cellular Processor Option Type (which is FREE_TEXT) has been defined as optional (O)

If we then have the following (exceedingly simple) Taxonomy structure:

We can assign the Option Types to each Taxon using a prototype, this is illustrated below:

Therefore when we create a Product in the Cellular Phones taxon, the following Option Values can be configured for that product:

Schema

The following is a simplified view of the key entity relationships for the object types we’ve discussed:

For a more detailed view you can interactively explore the GraphQL schema using GraphQL Voyager.

Creating a Taxonomy

The following steps illustrate the queries and mutations that you can use in the Operator API to create a taxonomy, points to note:

• We will create a simple taxonomy using all the concepts mentioned above, however detailed taxonomy design is outside the scope of this guide.

• These steps can be performed in the Operator Portal via the UI, we will be focused only on the API approach in this article.

  • You can read more about this approach in the Knowledge Base

  API Collections

  While we provide example GraphQL snippets in this article, you can also find the examples in the Marketplacer Operator API collections for Postman and Insomnia.

Taxonomy to Build

The Taxonomy we are going to build is a simplified version of the previous example:

1 . Create the Prototype

We’ll use the prototypeCreateOrUpdate mutation to create our Cellular Simplex prototype as follows:

mutation PrototypeCreateOrUpdate(
 $input: PrototypeCreateOrUpdateMutationInput!
) {
 prototypeCreateOrUpdate(input: $input) {
  errors {
   field
   messages
  }
  prototype {
   id
   name
  }
 }
}

Passing in the following variables:

{
  "input": {
    "name": "Cellular Simplex"
  }
}

Executing this mutation will return the following payload:

{
  "data": {
    "prototypeCreateOrUpdate": {
      "errors": null,
      "prototype": {
        "id": "UHJvdG90eXBlLTQ=",
        "name": "Cellular Simplex"
      }
    }
  }
}

Put aside the id value as we’ll need this in the steps that follow.

2. Create 2x Option Types

We want to create 2x Option Types:

• Cellular Material (applied to Advert)
• Cellular Memory (applied to Variant)

To do this we’ll use the optionTypeCreateOrUpdate mutation as follows:

mutation OptionTypeCreateOrUpdate(
 $input: OptionTypeCreateOrUpdateMutationInput!
) {
 optionTypeCreateOrUpdate(input: $input) {
  errors {
   field
   messages
  }
  optionType {
   id
   name
  }
 }
}

And we’ll execute it 2x with the following variable payloads:

Note we are supplying the prototype id for the prototype we created in step 1.

Variable Set for Cellular Material

{
  "input": {
    "prototypeIds": [
      "UHJvdG90eXBlLTQ="
    ],
    "name": "Cellular Material",
    "displayName": "Cellular Material",
    "appliedTo": "ADVERT",
    "fieldType": "SINGLE_SELECT",
    "optional": false
  }
}

Returns response

{
  "data": {
    "optionTypeCreateOrUpdate": {
      "errors": null,
      "optionType": {
        "id": "T3B0aW9uVHlwZS02",
        "name": "Cellular Material"
      }
    }
  }
}

Variable Set for Cellular Memory

{
  "input": {
    "prototypeIds": [
      "UHJvdG90eXBlLTQ="
    ],
    "name": "Cellular Memory",
    "displayName": "Cellular Memory",
    "appliedTo": "VARIANT",
    "fieldType": "SINGLE_SELECT",
    "optional": false
  }
}

Returns response

{
  "data": {
    "optionTypeCreateOrUpdate": {
      "errors": null,
      "optionType": {
        "id": "T3B0aW9uVHlwZS03",
        "name": "Cellular Memory"
      }
    }
  }
}

Put aside the 2x id values for the Option Types we just created as we’ll need these in the next step.

3. Create 4x Option Values

We want to create 4 Option Values for the 2 Option Types we just created:

• Plastic (Cellular Material)
• Aluminium (Cellular Material)
• 128Gb (Cellular Memory)
• 256Gb (Cellular Memory)

To do this we’ll use the optionValueCreateOrUpdate mutation as follows:

mutation OptionValueCreateOrUpdate(
 $input: OptionValueCreateOrUpdateMutationInput!
) {
 optionValueCreateOrUpdate(input: $input) {
  errors {
   field
   messages
  }
  optionValue {
   id
   name
  }
 }
}

And we’ll execute it 4x with the following variable payloads:

Note we are supplying the relevant option type ids for the option types we created in step 2.

Variable Set for Plastic

{
  "input": {
    "optionTypeId": "T3B0aW9uVHlwZS02",
    "displayName": "Plastic",
    "name": "Plastic"
  }
}

Returns response

{
  "data": {
    "optionValueCreateOrUpdate": {
      "errors": null,
      "optionValue": {
        "id": "T3B0aW9uVmFsdWUtNDg=",
        "name": "Plastic"
      }
    }
  }
}

Variable Set for Aluminium

{
  "input": {
    "optionTypeId": "T3B0aW9uVHlwZS02",
    "displayName": "Aluminium",
    "name": "Aluminium"
  }
}

Returns response

{
  "data": {
    "optionValueCreateOrUpdate": {
      "errors": null,
      "optionValue": {
        "id": "T3B0aW9uVmFsdWUtNDk=",
        "name": "Aluminium"
      }
    }
  }
}

Variable Set for 128Gb

{
  "input": {
    "optionTypeId": "T3B0aW9uVHlwZS03",
    "displayName": "128Gb",
    "name": "128Gb"
  }
}

Returns response

{
  "data": {
    "optionValueCreateOrUpdate": {
      "errors": null,
      "optionValue": {
        "id": "T3B0aW9uVmFsdWUtNTA=",
        "name": "128Gb"
      }
    }
  }
}

Variable Set for 256Gb

{
  "input": {
    "optionTypeId": "T3B0aW9uVHlwZS03",
    "displayName": "256Gb",
    "name": "256Gb"
  }
}

Returns response

{
  "data": {
    "optionValueCreateOrUpdate": {
      "errors": null,
      "optionValue": {
        "id": "T3B0aW9uVmFsdWUtNTE=",
        "name": "256Gb"
      }
    }
  }
}

4. Create our Taxons

In this last step we’ll create our 2 Taxons:

• Cellular Technology
• Cellular Internet

To do so well use the taxonCreateOrUpdate mutations as follows:

mutation TaxonCreateOrUpdate($input: TaxonCreateOrUpdateMutationInput!) {
 taxonCreateOrUpdate(input: $input) {
  status
  errors {
   field
   messages
  }
  taxon {
   id
  }
 }
}

And we’ll execute it 2x with the following variable payloads:

Variable Set for Cellular Technology

Note: we are not supplying a prototype Id for this Taxon

{
  "input": {
    "displayName": "Cellular Technology",
    "title": "Cellular Technology"
  }
}

Returns response:

{
  "data": {
    "taxonCreateOrUpdate": {
      "status": 200,
      "errors": null,
      "taxon": {
        "id": "VGF4b24tNQ=="
      }
    }
  }
}

Retain the taxon id as we’ll need it in the next step.

Variable Set for Cellular Internet

{
  "input": {
    "prototypeId": "UHJvdG90eXBlLTQ=",
    "parentId": "VGF4b24tNQ==",
    "displayName": "Cellular Internet",
    "title": "Cellular Internet"
  }
}