EmailTemplate - Default Only or direct DB available?
In the sourcecode you provide the raw HTML file that is used for email generation when the SMTP email is sent:
zitadel/internal/notification/static/templates
/template.html
From my reading of the documentation, in defaults.yml you provide EmailTemplate: which is a subsection of DefaultInstance:. Based on my investigation this is actually a base64 conversion of the html file above. -- As my instance is already setup and using EmailTemplate won't work for us have found that this file exists in hex format over in zitadel.projections.mail_templates2. There is only one instance with a hex entry in template(bytea).
- I found this after reading the outdated DB Schema for "Notifications" - https://zitadel.com/docs/concepts/eventstore/implementation#schemas
I pipped the binary into xxd -r -p > template_maybe.html and after doing an sdiff it appears to be the same file.
QUESTION 1 - I know its a total work-around compared to writing our own HTTP Provider handler, but would this work if we just updated the database with the binary conversion of our own formatted html file?
QUESTION 2 - If we already ran init(like we have), would DefaultInstance:EmailTemplate be updated on a setup/start or any subsequent run on star-from-init if we included an updated base64 version our own html file to our config file based on the default provided in zitadel/cmd
/defaults.yaml?
HTTP Provider - https://zitadel.com/docs/guides/manage/customize/notification-providers#webhook--http-provider
API - Add HTTP Provider - https://zitadel.com/docs/apis/resources/admin/admin-service-add-email-provider-http4 Replies
Hi @Larzous, thanks for reaching out! Please find my answers below:
1. Don’t patch the
projections.mail_templates2 row.
That table is only a projection – a read-model that ZITADEL rebuilds from the event store. As soon as ZITADEL rereads the events (on restart, spooler catch-up or during an upgrade) your manual change will be overwritten and the other nodes in a cluster will never see it. The canonical way to ship a new e-mail layout is to switch to an HTTP provider that sends the HTML on your side. Editing the projection directly is unsupported and would be a temporary workaround.
2. DefaultInstance.EmailTemplate (or FirstInstance.EmailTemplate in steps.yaml) is only read once during zitadel init. After the first successful setup, subsequent zitadel start-from-init or normal restarts ignore that section because the instance already exists and the init job is idempotent. If you add or change the base-64-encoded HTML later, nothing will happen.
I hope this answers your questions. Please let me know if you have any other doubts!Now I'm just curious -- so if an instance was build using a different
DefaultInstance.EmailTemplate how does that even get changed?
If you ever update the default template files, how does that get pushed to instance updates? -- Or is this the result of template.html being compiled into the application?
/internal/notification/static/templates/template.html
I personally don't think we should fork just for this( someone will build a http provider), but one of the Devs was asking.Hey @Larzous I'm looking into this query, I'll let you know as soon as I get clarification from one of our Engineers working directly on this.
Hi @Larzous, this was the answer from Engineering:
To sumarize:
After init, a newer template.html in a ZITADEL release is only used for brand-new instances; it never overwrites existing events.
More details:
The functionality to change the template after a setup would be available in the code, but is not yet implemented as API. You can technically update the projection, which would be overwritten again if you recompute the projection, so we never recommend the edit there.
I hope that answers your questions, but please let me know if something is unclear 😄
Thanks for the info. I understand our need to build our own HTTP Provider.
What has me puzzled is that this is something that was imbedded into a database, and no amount of "upgrading" can ever change it in the deployment. --- IE -- once its set, its set FOREVER unless you init a new DB and migrate users into it?
To me, this seems like something you would want to be updated any time you
start-from-setup rather than init only.
But I agree -- updating the projection is probably very ill-advised since I don't want it to have to keep being updated if the service restarts (systemctl services) as I have it setup currently.