{"id":23143726,"url":"https://github.com/digitalinteraction/gform-to-trello","last_synced_at":"2025-04-04T12:14:57.066Z","repository":{"id":49604996,"uuid":"236479679","full_name":"digitalinteraction/gform-to-trello","owner":"digitalinteraction","description":"A tool for listening to Google form responses and generating Trello cards from them","archived":false,"fork":false,"pushed_at":"2021-08-31T12:18:48.000Z","size":648,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-09T22:11:21.500Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalinteraction.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-27T11:52:10.000Z","updated_at":"2024-11-08T12:31:43.000Z","dependencies_parsed_at":"2022-09-15T01:13:08.517Z","dependency_job_id":null,"html_url":"https://github.com/digitalinteraction/gform-to-trello","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fgform-to-trello","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fgform-to-trello/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fgform-to-trello/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fgform-to-trello/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalinteraction","download_url":"https://codeload.github.com/digitalinteraction/gform-to-trello/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174467,"owners_count":20896078,"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-12-17T15:14:06.694Z","updated_at":"2025-04-04T12:14:57.034Z","avatar_url":"https://github.com/digitalinteraction.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gform-to-trello\n\nThis repo is a [Node.js](https://nodejs.org/en/) server\nwhich reacts to [Google Form](https://www.google.com/forms/about/) submissions\nand uses templates and variables to generate [Trello](https://trello.com/home) cards.\n\nThere is also a tool for generating a [Google Apps Script](https://developers.google.com/apps-script/)\nto process form responses and send data to the node server.\n\n\u003c!-- toc-head --\u003e\n\n## Table of contents\n\n- [Usage](#usage)\n  - [Environment variables](#environment-variables)\n  - [Mounted files](#mounted-files)\n    - [mapping.yml](#mappingyml)\n    - [content.njk](#contentnjk)\n- [Development](#development)\n  - [Setup](#setup)\n  - [Regular use](#regular-use)\n  - [Irregular use](#irregular-use)\n  - [Testing](#testing)\n  - [Commits](#commits)\n  - [Code formatting](#code-formatting)\n  - [Building the image](#building-the-image)\n  - [Google scripts](#google-scripts)\n  - [Exploring the Trello api](#exploring-the-trello-api)\n  - [Future work](#future-work)\n\n\u003c!-- toc-tail --\u003e\n\n## Usage\n\nBelow is info on how to configure and run the docker image.\nThe image will crash if any values are not set.\n\n```bash\n# For example ...\ndocker run \\\n  --env-file=.env \\\n  -v `pwd`/content.njk:/app/res/content.njk \\\n  -v `pwd`/mapping.yml:/app/res/mapping.yml \\\n  -p 3000:3000 \\\n  openlab.ncl.ac.uk:4567/catalyst/gform-trello-magic:$VERSION\n```\n\n### Environment variables\n\n- `TRELLO_APP_KEY` ~ https://trello.com/app-key\n- `TRELLO_TOKEN` ~ Trello auth token generated with `TRELLO_APP_KEY`\n- `TRELLO_BOARD_ID` ~ The board to use\n- `TRELLO_INBOX_LIST_ID` ~ The list to put form responses into\n- `HOOK_SECRET` ~ A secret to authenticate creating cards\n\n\u003e For help on trello variables, [Setup](#setup) might be useful\n\n### Mounted files\n\nThese files need to be mounted into the container when you run it,\nwithout them the image won't know how to process form responses.\nThe image will crash if they are not set.\n\n#### mapping.yml\n\nThis should be mounted at `/app/res/mapping.yml`.\nIt is responsible for mapping google form ids to human names\nand telling the image how to match tags.\n\nWhen processing, if a value is not found for that key/path it is set to `null`\n\n```yaml\n# This sections maps google form ids to human-readable names\nfields:\n  123456:\n    person.name\n  123456:\n    person.age\n  123456:\n    person.pets\n\n# This section tells the image how to match tags on form responses\nlabels:\n  person.pets:  # the field to match labels on (works with any text or checkbox)\n    prefix: pet # The prefix of the label, e.g. will generate pet:dog and pet:cat\n    color: lime # The color to create labels if they don't already exist\n```\n\n\u003e For more info see [types.ts](src/types.ts)'s MappingConfig.\n\nTo get field ids there is a `#onOpen` event handler in the `google-scripts/eoi-form` script\nwhich if you hook up to a Google form opening it will log all the fields.\nYou can get this log on the script's page under `View \u003e Logs`.\n\n#### content.njk\n\nThis should be mounted at `/app/res/content.njk`.\nThis file is a [Nunjucks](https://mozilla.github.io/nunjucks/) template\nused to generate a card's description.\nIt has all the fields from [mapping.yml](#mapping.yml) under the `data` object\nso you can generate the card description based on any mapped field value.\n\n```md\n# {{ data.person.name }}\n\n\u003e AGE: {{ data.person.age }}\n```\n\n## Development\n\nBelow is information about developing on this repo.\n\n### Setup\n\nTo develop on this repo you will need to have [Docker](https://www.docker.com/) and\n[node.js](https://nodejs.org) installed on your dev machine and have an understanding of them.\nThis guide assumes you have the repo checked out and are on macOS.\n\nYou will need a [trello account](https://trello.com/home) with access to a board to link with.\n\nYou'll only need to follow this setup once for your dev machine.\n\n```bash\n# Install node dependencies\nnpm install\n\n# Start creating your env\ncp .env.example .env\n\n# 1. Set your TRELLO_APP_KEY in .env\nopen https://trello.com/app-key\n\n# 2. Generate and set your TRELLO_TOKEN in .env\nnpm run cli:dev trello:auth\n\n# 3. Get and set your TRELLO_BOARD_ID in .env\nnpm run cli:dev trello:boards\n\n# 4. Pick your TRELLO_INBOX_LIST_ID in .env\nnpm run cli:dev trello:lists\n```\n\n### Regular use\n\nThese are the commands you'll regularly run to develop the API, in no particular order.\n\n```bash\n# Run unit tests\n# -\u003e Runs any \".spec.ts\" file in the \"src\" folder\nnpm run test\n\n# Run the cli directly\n# -\u003e runs typescript on-the-go using ts-node\n# -\u003e the -- stops npm-run slurping dash-dash parameters\nnpm run cli:dev -- --help\n\n# Run the server locally\n# -\u003e Requests a valid .env ~ it'll let you know\n# -\u003e Runs on port 3000 by default\nnpm run cli:dev server\n\n# Test a content.njk\n# -\u003e Uses res/content.njk as the template\n# -\u003e Uses res/dummy-content.json as the data to render with\n#    Make this to the same shape your mapping.yml will produce\n# -\u003e Outputs the generated markdown to the terminal\nnpm run cli:dev test:content res/dummy-content.json\n```\n\n### Irregular use\n\nThese are commands you might need to run but probably won't, also in no particular order.\n\n```bash\n# Manually compile javascript from typescript\nnpm run build\n\n# Find linter errors\nnpm run lint\n\n# Run the production CLI\n# -\u003e Needs javascript to be compilled\n# -\u003e Doesn't load the local .env\nnpm run cli:prod\n\n# Generate the table of contents in this readme\nnpm run generate:toc\n```\n\n### Testing\n\nThis repo uses [unit tests](https://en.wikipedia.org/wiki/Unit_testing)\nto ensure that everything is working correctly, guide development, avoid bad code and reduce defects.\nIt uses [Jest](https://www.npmjs.com/package/jest) to run unit tests.\nTests are any file in `src/` that end with `.spec.ts`, by convention they are inline with the source code,\nin a parallel folder called `__tests__`.\n\nThese tests are also run as a CI when you push to git.\n\n```bash\n# Run the tests\nnpm test -s\n\n# Generate test coverage to find gaps\nnpm run coverage -s\nopen coverage/lcov-report/index.html\n```\n\n### Commits\n\nAll commits to this repo must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).\nThis ensures changes are structured and means the [CHANGELOG.md](/CHANGELOG.md) can be automatically generated.\n\nThis standard is enforced through a `commit-msg` hook using [yorkie](https://www.npmjs.com/package/yorkie).\n\n### Code formatting\n\nThis repo uses [Prettier](https://prettier.io/) to automatically format code to a consistent standard.\nIt works using the [husky](https://www.npmjs.com/package/husky)\nand [lint-staged](https://www.npmjs.com/package/lint-staged) packages to\nautomatically format code whenever code is committed.\nThis means that code that is pushed to the repo is always formatted to a consistent standard.\n\nYou can manually run the formatter with `npm run prettier` if you want.\n\nPrettier is slightly configured in [package.json](/package.json)\nand also ignores files using [.prettierignore](/.prettierignore).\n\n### Building the image\n\nThis repo uses a [GitLab CI](https://about.gitlab.com/product/continuous-integration/)\nto build a Docker image when you push a git tag.\nThis is designed to be used with the `npm version` command so all docker images are [semantically versioned](https://semver.org/).\nThe `:latest` docker tag is not used.\n\nThis job runs using the [.gitlab-ci.yml](/.gitlab-ci.yml) file which\nruns a docker build using the [Dockerfile](/Dockerfile)\nand **only** runs when you push a [tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging).\n\nIt pushes these docker images to the GitLab registry of the repo.\n\n```bash\n# Generate a new release\n# -\u003e Generates a new version based on the commits since the last version\n# -\u003e Generates the CHANGELOG.md based on those commits\n# -\u003e There is a \"preversion\" script to lint \u0026 run tests\nnpm run release\n\n# Push the new version\n# -\u003e The GitLab CI will build a new docker image for it\ngit push --follow-tags\n```\n\n### Google scripts\n\nThis repos also uses [clasp](https://github.com/google/clasp)\nto sync local `.ts` files with Google App Scripts.\nSo you can develop scripts locally with typescript types\nand push them up to be run on events i.e. onFormSubmit.\n\n\u003e [Intro to clasp](https://codelabs.developers.google.com/codelabs/clasp)\n\nTheres an interactive script that will attempt to `clasp push`\nany directory in `google-scripts`\n\n```\n./scripts/push-clasp.sh\n```\n\nTo add a new clasp folder:\n\n```bash\ncd google-scripts/new-dir\n\n# Clone the project into the currect directory\nnpx clasp clone $SCRIPT_ID\n\n# Open the code in the browser\nnpx clasp open\n```\n\n### Exploring the Trello api\n\nBelow are some useful scripts for inspecting what Trello's API gives you.\nExamples use [httpie](https://httpie.org).\n\n```bash\n# Add your environment variables to your dev machine's env so we can use them\nsource .env\n\n# fetchOrganizations\nhttp https://api.trello.com/1/members/me/organizations key==$TRELLO_APP_KEY token==$TRELLO_TOKEN\n\n# fetchBoards\nhttp https://api.trello.com/1/members/me/boards key==$TRELLO_APP_KEY token==$TRELLO_TOKEN\n\n# fetchLabels\nhttp https://api.trello.com/1/boards/$TRELLO_BOARD_ID/labels key==$TRELLO_APP_KEY token==$TRELLO_TOKEN\n\n# fetchLists\nhttp https://api.trello.com/1/boards/$TRELLO_BOARD_ID/lists key==$TRELLO_APP_KEY token==$TRELLO_TOKEN cards==open\n```\n\n### Future work\n\n- Explore better ways of handling clasp deployments\n- Look into handling Trello API pagination\n- git-ignore the `res` folder for easier testing mapping/content\n- Create an npm package with the cli to deploy the scraper and test files\n- Improve documentation for setting up of Google Apps Scripts\n- Push docker images to dockerhub\n\n---\n\n\u003e The code on https://github.com/unplatform/gform-to-trello is a mirror of https://openlab.ncl.ac.uk/gitlab/catalyst/gform-trello-magic\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalinteraction%2Fgform-to-trello","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalinteraction%2Fgform-to-trello","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalinteraction%2Fgform-to-trello/lists"}