{"id":18347995,"url":"https://github.com/collaborne/miro-templating","last_synced_at":"2025-04-13T13:33:40.165Z","repository":{"id":57298253,"uuid":"265217138","full_name":"Collaborne/miro-templating","owner":"Collaborne","description":"Create new Miro boards based on templates. Includes tools to create \u0026 test the templates.","archived":false,"fork":false,"pushed_at":"2024-01-09T16:45:17.000Z","size":106,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-05T21:46:06.506Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Collaborne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-05-19T10:31:23.000Z","updated_at":"2024-04-10T14:28:51.000Z","dependencies_parsed_at":"2024-01-05T08:40:56.141Z","dependency_job_id":null,"html_url":"https://github.com/Collaborne/miro-templating","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Collaborne%2Fmiro-templating","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Collaborne%2Fmiro-templating/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Collaborne%2Fmiro-templating/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Collaborne%2Fmiro-templating/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Collaborne","download_url":"https://codeload.github.com/Collaborne/miro-templating/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231007295,"owners_count":18314154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T21:16:00.794Z","updated_at":"2024-12-23T19:13:42.764Z","avatar_url":"https://github.com/Collaborne.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# miro-templating\n\n[Miro.com](https://www.miro.com) is an online whiteboard for visual collaboration. It comes with a great UI to build and collaborate canvases. Miro offers as well an API to programmatically create new boards.\n\nThis library allows the templating of Miro boards:\n\n* Create new boards via the Miro API based on a JSON template - including placeholders that are replaced during board creation\n* Query specific user created data within the Miro board, e.g. ideas posted in a specific box within the Miro board\n\nThe repository contains as well tools to create \u0026 test the templates.\n\nThis [blog post](https://medium.com/collaborne-engineering/templating-miro-com-boards-bac21271a7d9?source=friends_link\u0026sk=b8b423bedec60517dd766f4ac7b87561) provides further information about the aim of this library.\n\n## Install\n\n### Prerequisites\n\nEnsure you have installed:\n\n* [Git client](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)\n* [Node \u0026 npm](https://nodejs.org/en/)\n* Sign up for a miro.com account\n\n### Install tools\n\nInstall the tools via npm:\n\n```sh\nnpm install -g miro-templating\n```\n\n_Note that installing packages globally may require administrative privileges._\n\n### Create Miro token\n\nFollowing [Miro documentation](https://developers.miro.com/docs/getting-started) and create an access token with these permissions:\n\n* boards:read\n* boards:write\n\nAlso note the `Client id` as you will need it later on (`MIRO_CLIENT_ID`).\n\n## Usage\n\n### Overview\n\nThe Miro API supports only a subset of the features exposed in the Miro UI (e.g. labels aren't available via the API). It's therefore an iterative process of creating a Miro template that looks good and works via the API.\n\nThe overall process is:\n\n1. Create your ideal Miro board via the Miro UI\n2. Auto-create a template based on the Miro board\n3. Create a new Miro board based on the template\n4. Review the created board in the Miro UI\n5. Remove/adjust parts in the template that don't work via the API\n6. Repeat steps 2-5 until the template looks good\n\n#### Note for Windows\n\nThe example commands are written with a Unix/Linux shell in mind, `VAR1=value1 VAR2=value2 command` reads as \"run `command` with the environment variables `VAR1` and `VAR2` set to the given values\". On Windows with the `cmd` shell this translates to multiple commands:\n\n```cmd\nset VAR1=value1\nset VAR2=value2\ncommand\nset \"VAR1=\"\nset \"VAR2=\"\n```\n\n### Auto-generate template from Miro\n\nUse this command to create a new template based on an existing Miro board:\n\n```sh\nMIRO_TOKEN=\u003cTOKEN\u003e BOARD_ID=\u003cBOARD_ID\u003e TEMPLATE_ID=\u003cTEMPLATE_ID\u003e create-miro-template\n```\n\nThe command states the path where the template was created.\n\n| Parameters | Explanation |\n| ---------- | ----------- |\n| BOARD_ID | You find the board-ID in the URL of your Miro board: `https://miro.com/app/board/a2J_kuG_mO0=/` =\u003e BOARD_ID is `a2J_kuG_mO0=`\u003cbr\u003e**The board must be in the same Miro team that was choosen when creating the Miro token!** |\n| TEMPLATE_ID | ID of how to name your template, e.g. `test` |\n\nYou can rerun the tool to update the widgets. The tool won't overwrite your configured name, etc. in the template.\n\n### Create Miro board from template\n\nUse this command to create a Miro board based on a template:\n\n```sh\nMIRO_TOKEN=\u003cTOKEN\u003e MIRO_CLIENT_ID=\u003cCLIENT_ID\u003e TEMPLATE_ID=\u003cTEMPLATE_ID\u003e create-miro-board\n```\n\n| Parameters | Explanation |\n| ---------- | ----------- |\n| MIRO_CLIENT_ID | ID of the Miro client, e.g. `1234567890123456789` |\n| TEMPLATE_ID | ID of how to name your template, e.g. `test` |\n\n## Templating\n\n### Markdown\n\nThe tools converts HTML content into markdown and back. This eases the translation of templates.\n\nBe aware that HTML -\u003e markdown -\u003e HTML conversion can lead to data loss because markdown can't represent the same richness as HTML.\n\n### Placeholders\n\nYou can use placeholders in the templates. These placeholders are filled at the time when the Miro board is created.\n\nThe following template snippet includes the project name into the text of the widget:\n\n```json\n{\n  \"widgets\": [\n    {\n      \"type\": \"shape\",\n      \"text\": \"Board for ${PROJECT_NAME}\",\n```\n\nThe value of the placeholder is extracted from the file [sample/context.json](sample/context.json). This is for testing only. In production usage, set these values programmatically.\n\n## Query texts from Miro board\n\n`miro-templating` allows to query back data entered into a Miro board. For this, target areas can be marked via [Miro's metadata](https://developers.miro.com/reference#application-metadata). All texts within this target area are queried (incl. the text in the target area itself). For example, you could define a box and get the text of all stickies within this box returned.\n\n### Define target areas for querying\n\nTo declare target area, add the field `metadata` with the `import_type`. For example, the following template declares a target area:\n\n```json\n{\n  \"widgets\": [\n    {\n      \"type\": \"shape\",\n      \"metadata\": {\n        \"${APP_ID}\": {\n          \"import_type\": \"idea\"\n        }\n      }\n```\n\nYou can define multiple target areas in a template. These can have the same - or different - values for `import_type`.\n\nGood to know:\n\n* The placeholder `${APP_ID}` is automatically replaced with your Miro client ID when creating the board. It's necessary to use the Miro client ID (= `APP_ID`) when creating the board and when querying it.\n* The query logic supports currently only rectangular target areas.\n* **The metadata markers are stored in Miro. This means that querying is only going to work with Miro boards that were newly created with the template. In other words: you cannot add metadata markers to existing Miro boards!**\n\n### Query target areas\n\nUse this command to create a Miro board based on a template:\n\n```sh\nMIRO_TOKEN=\u003cTOKEN\u003e MIRO_CLIENT_ID=\u003cCLIENT_ID\u003e BOARD_ID=\u003cBOARD_ID\u003e query-miro-board\n```\n\n| Parameters | Explanation |\n| ---------- | ----------- |\n| MIRO_CLIENT_ID | ID of the Miro client, e.g. `1234567890123456789` |\n| BOARD_ID | You find the board-ID in the URL of your Miro board: `https://miro.com/app/board/a2J_kuG_mO0=/` =\u003e BOARD_ID is `a2J_kuG_mO0=` |\n\nAll results are marked with the `import_type` of the target area:\n\n```json\n{\n  \"hits\": [\n    { \"type\": \"idea\", \"value\": \"Idea 1\" },\n    { \"type\": \"idea\", \"value\": \"Idea 2\" }\n  ]\n}\n```\n\n## FAQ\n\n### Why do I get errors from the Miro API when creating a board based on an imported board?\n\nThe Miro API supports only a subset of the UI features (e.g. transparent borders exists only in the UI). Additionally, the Miro API exports JSON that sometimes isn't support by the Miro create API (e.g. Miro export contains widgets with `borderWidth=1` wheras Miro create API forbids `borderWidth=1`).\n\nIf you encounter one of these situations:\n\n1. Understand from the Miro API error which widget/field causes the issue\n2. Adjust the template accordingly for this widget to prevent the error\n3. Try again to create the board\n\nExample: you can emulate a transparent border by setting `borderWidth=0` or by setting color to white (if it's shown on a white background).\n\nThe Miro API community is a great starting point to investigate these situations: \u003chttps://community.miro.com/search/index?tags%5B0%5D=api\u003e.\n\n## Others\n\nMiro is a trademark registered by RealtimeBoard, Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcollaborne%2Fmiro-templating","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcollaborne%2Fmiro-templating","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcollaborne%2Fmiro-templating/lists"}