Assigning custom IDs

By default any entries in blocks, results, and items are assigned an auto incremented ID. This behaviour can be changed and the IDs can be set explicitly which makes it easier to later work with the Riddle's stats or webhook data.

Additionally it makes it easier to configure custom logic settings based on the IDs you have assigned.

How IDs are assigned

• Every ID has to be a positive integer (1 or greater). Sending 0 or a negative number is rejected with Block ID must be a positive integer, <id> given.
• Auto-generated IDs also start at 1 and count up. The Riddle remembers which IDs it has handed out, so you can mix explicit IDs and auto-generated ones freely - an auto-generated ID never re-uses an ID you assigned yourself.
• blocks and result/results share one ID namespace, so a result cannot re-use a block's ID (in a personality test, personalities and attributes share that namespace as well).
• Item IDs only have to be unique within their own block.
• Re-using an ID inside one namespace fails the build with ... with ID <id> already exists. / Item with ID <id> already exists. Make sure to not provide overlapping IDs.

IDs when editing a Riddle

Editing an existing Riddle addresses blocks by the IDs they are already stored with, so two more things matter there:

• The ID counter only ever grows and is shared across blocks, results, personalities and attributes. An ID freed by a deletion is never handed out again, and no ID visible in the build configuration tells you which one is free - the highest block ID plus one is usually already taken by a result.
• Read the free ID from nextBlockId, which GET /riddle-builder/{UUID} returns. Claiming a taken ID is rejected with an error naming the next free one.

Riddles built in the Creator can number their content from 0 upwards. An edit accepts such IDs so a configuration read from the API can be sent back unchanged; a newly added block ("$create": true) still needs a positive ID.

Custom block IDs

You can assign a custom ID to any block by adding the id property to the block object. The ID must be a positive integer (1 or greater) and unique (not used in blocks + result/results).

Example object:

{
    "id": 101,
    "title": "The best noodles?",
    "type": "SingleChoice",
    "items": [
        { "title": "Spaghetti" },
        { "title": "Fusilli" }
    ]
}

Custom item IDs

You can assign a custom ID to any item by adding the id property to the item object. The ID must be a positive integer (1 or greater) and unique (only within the same block). Every collection is an array of objects (see item formats), so id simply joins the other keys of the entry:

{
    "items": [
        {
            "id": 201,
            "title": "Spaghetti"
        },
        {
            "id": 202,
            "title": "Fusilli"
        }
    ]
}

Custom result IDs

You can assign a custom ID to any result by adding the id property to the result object. The ID must be a positive integer (1 or greater) and unique (not used in blocks + result/results).

Example simple result:

{
    "id": 301,
    "title": "Thank you",
    "description": "Thanks for your vote."
}

Example advanced result page with blocks:

{
    "id": 302,
    "blocks": [
        {
            "type": "Text",
            "text": "<h1>Thank you!</h1><p>Thanks for your vote.</p>"
        }
    ]
}

Full example

{
    "type": "Poll",
    "build": {
        "title": "Favorite color poll",
        "blocks": [
            {
                "id": 101,
                "title": "What's your favorite color?",
                "type": "SingleChoice",
                "items": [
                    {
                        "id": 201,
                        "title": "green"
                    },
                    {
                        "id": 202,
                        "title": "red"
                    }
                ]
            }
        ],
        "result": {
            "id": 301,
            "title": "Thank you",
            "description": "Thanks for your vote."
        }
    }
}