{"type":"doc","content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"blue","style":"bold","text":"Version 10","localId":"2360215e-0f04-4033-a43a-8f5ea81590f9"}},{"text":" ","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"style":{"value":"none"}},"macroMetadata":{"macroId":{"value":"1d073435-435b-45bd-83d7-a83a9e63a2da"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"c4677043-e2b6-4c41-a158-22d0816fbe44"}},{"type":"paragraph","content":[{"text":"PIPEFORCE comes with a comprehensive multi-channel and multi-language framework which allows to generate notification messages dynamically from templates in different multiple languages and send them to multiple channels. Such a target channel for example can be : Email, Slack, Teams, SMS, WhatsApp, Message Queue and many others.","type":"text"}]},{"type":"paragraph","content":[{"text":"Additionally, this framework includes also push events. This means a user or group of users can subscribe to certain PIPEFORCE events. Every time such an event happens, they will be informed about this on the configured channel in the preferred language.","type":"text"}]},{"type":"paragraph","content":[{"text":"Target addresses of notifications can be for example email addresses, IAM usernames, IAM group names, chat groups or other custom addresses as further described below.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"What is the difference between a ","type":"text","marks":[{"type":"strong"}]},{"text":"message","type":"text","marks":[{"type":"underline"},{"type":"strong"}]},{"text":" and a ","type":"text","marks":[{"type":"strong"}]},{"text":"notification","type":"text","marks":[{"type":"underline"},{"type":"strong"}]},{"text":"?","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"A notification is usually send to a human user. It is a subset of the message class since a message can be any kind of information send to users and or systems.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Quick Start Guides","type":"text"}]},{"type":"paragraph","content":[{"text":"For those not interested in the details but want to have a quick result, here are the quick start guides for the most common use cases using the notification framework.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Send a plain text email (simple mode)","type":"text"}]},{"type":"paragraph","content":[{"text":"In case you would like to send a simple plain text email to a given set of email addresses, you can simply use a pipeline like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - notification.send:\n to: [\"email1@domain.tld\", \"email2@domain.tld\"]\n cc: [\"email3@domain.tld\"]\n bcc: [\"email4@domain.tld\"]\n subject: \"This is the subject\"\n message: \"This is the plain text body.\"\n attachments: [\"$uri:attachment:path/to/attachment\"]\n","type":"text"}]},{"type":"paragraph","content":[{"text":"The notification framework will automatically detect the target channel (which is email in this example) and renders and sends the according mime message for you. This is the easiest approach. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Aliases to the ","type":"text"},{"text":"notification.send","type":"text","marks":[{"type":"code"}]},{"text":" command are ","type":"text"},{"text":"notifcation.put","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"mail.send","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]},{"type":"paragraph","content":[{"text":"In some cases you might have the requirement to further customize the mime message. For this, see the examples below for more details.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Send a plain text email (customize mode)","type":"text"}]},{"type":"paragraph","content":[{"text":"In case you would like to further customize the mime headers or the multipart body of an email, you can use this approach instead:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - notification.send:\n input: {\n \"headers\": {\n \"to\": [\"email1@domain.tld\", \"email2@domain.tld\"],\n \"cc\": [\"email3@domain.tld\"],\n \"bcc\": [\"email4@domain.tld\"],\n \"subject\": \"This is the subject\",\n }\n \"body\": {\n \"contentType\": \"text/plain\",\n \"content\": \"This is the plain text body.\"\n }\n }","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that the notification ","type":"text"},{"text":"input","type":"text","marks":[{"type":"code"}]},{"text":" is a 100% mime message (","type":"text"},{"text":"RFC2045","type":"text","marks":[{"type":"link","attrs":{"href":"https://datatracker.ietf.org/doc/html/rfc2045"}}]},{"text":". ) compliant format. This means it is separated into a ","type":"text"},{"text":"headers","type":"text","marks":[{"type":"code"}]},{"text":" and a ","type":"text"},{"text":"body","type":"text","marks":[{"type":"code"}]},{"text":" section. In the headers section all headers from the MIME standard are supported. They will be forwarded to the target channel, like email client for example. Also the body section is fully compliant with RFC2045 so you can construct any multipart body structure you need for the target client. For further details about such a structure please consult external documentation about how to construct valid multipart mime messages.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Send a mixed-content multipart mime message","type":"text"}]},{"type":"paragraph","content":[{"text":"In case you would like to compose a multipart mime message with mixed content, you can use this example as a template:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - notification.send:\n input: {\n \"headers\": {\n \"to\": [\"email1@domain.tld\", \"email2@domain.tld\"],\n \"cc\": [\"email3@domain.tld\"],\n \"bcc\": [\"email4@domain.tld\"],\n \"subject\": \"This is the subject\",\n }\n \"body\": {\n \"contentType\": \"multipart/mixed\",\n \"content\": [\n {\n \"contentType\": \"multipart/alternative\",\n \"content\": [\n {\n \"contentType\": \"text/plain; charset=UTF-8\",\n \"content\": \"This is the plain text body.\"\n },\n {\n \"contentType\": \"text/html; charset=UTF-8\",\n \"content\": \"$uri:property:global/app/my.app/template/body\"\n }\n ]\n },\n {\n \"contentType\": \"image/jpeg\",\n \"contentDisposition\": \"attachment; filename=\\\"bild.jpg\\\"\",\n \"contentTransferEncoding\": \"base64\",\n \"content\": \"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAHBgoJCAkLC...\"\n },\n {\n \"contentType\": \"application/pdf\",\n \"contentDisposition\": \"attachment; filename=\\\"dokument.pdf\\\"\",\n \"contentTransferEncoding\": \"outbound\",\n \"content\": \"$uri:attachment:some-attachment-uuid\"\n }\n ]\n }\n }\n }\n \n ","type":"text"}]},{"type":"paragraph","content":[{"text":"For specific details about the structure of a multipart mime message, please have look at the ","type":"text"},{"text":"RFC2045","type":"text","marks":[{"type":"link","attrs":{"href":"https://datatracker.ietf.org/doc/html/rfc2045"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"As you can see in this example, the ","type":"text"},{"text":"body","type":"text","marks":[{"type":"code"}]},{"text":" can be a list of ","type":"text"},{"text":"nested content","type":"text","marks":[{"type":"strong"}]},{"text":" objects.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"content","type":"text","marks":[{"type":"code"}]},{"text":" value itself can be a fixed text, a base64 string or a ","type":"text"},{"text":"PIPEFORCE URI","type":"text","marks":[{"type":"link","attrs":{"href":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2548727819"}}]},{"text":" pointing to a resource to load.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Attachments","type":"text"}]},{"type":"paragraph","content":[{"text":"You can also add (file) attachments to notifications. Depending on the target channel they will be provided as downloads or embedded when the notification shows-up in the channel client.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Simple Mode","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to add (file) attachments to your notification, you have multiple options. The easiest approach is to use the ","type":"text"},{"text":"attachments","type":"text","marks":[{"type":"code"}]},{"text":" attribute of the ","type":"text"},{"text":"notification.send","type":"text","marks":[{"type":"code"}]},{"text":" command:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - notification.send:\n to: [\"email1@domain.tld\", \"email2@domain.tld\"]\n subject: \"This is the subject\"\n message: \"This is the plain text body.\"\n attachments: [\"$uri:attachment:path/file1\", \"$uri:attachment:path/file2\"]","type":"text"}]},{"type":"paragraph","content":[{"text":"The command will try to autodetect all required attachment information from the list of given attachments and append it to the body content in multipart mime format at the very end. It wont overwrite any existing part there. ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Combined Mode","type":"text"}]},{"type":"paragraph","content":[{"text":"This way you can combine the simplified parameter format with a specific one. For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - notification.send:\n to: [\"email1@domain.tld\", \"email2@domain.tld\"]\n subject: \"This is the subject\"\n attachments: [\"$uri:attachment:path/file1\", \"$uri:attachment:path/file2\"]\n input: {\n \"body\": {\n \"contentType\": \"text/plain\",\n \"content\": \"This is the plain text body.\"\n }\n }","type":"text"}]},{"type":"paragraph","content":[{"text":"The final multipart mime message, which will be send to the email channel will be this (since the simplified parameters are merged into the input notification):","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"headers\": {\n \"to\": [\"email1@domain.tld\", \"email2@domain.tld\"],\n \"subject\": \"This is the subject\"\n }\n \"body\": {\n \"contentType\": \"multipart/mixed\",\n \"content\": [\n {\n \"contentType\": \"text/plain\",\n \"content\": \"This is the plain text body.\"\n },\n {\n \"contentType\": \"application/pdf\",\n \"contentDisposition\": \"attachment; filename=\\\"file1\\\"\",\n \"contentTransferEncoding\": \"outbound\",\n \"content\": \"$uri:attachment:path/file1\"\n },\n {\n \"contentType\": \"application/pdf\",\n \"contentDisposition\": \"attachment; filename=\\\"file2\\\"\",\n \"contentTransferEncoding\": \"outbound\",\n \"content\": \"$uri:attachment:path/file2\"\n }\n ]\n }\n }\n}","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Note: ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"All given values from command parameters will overwrite the values in the mime message if there are any. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In case the section doesn’t exist yet in the mime message, it will be created. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It could be that the original mime message needs to be re-arranged to insert the parameter values: For example in case you would like to add ","type":"text"},{"text":"attachments","type":"text","marks":[{"type":"code"}]},{"text":" via command parameter to an existing ","type":"text"},{"text":"text/plain","type":"text","marks":[{"type":"code"}]},{"text":" input body. In this case, the body will be converted to ","type":"text"},{"text":"multipart/mixed","type":"text","marks":[{"type":"code"}]},{"text":" and the text plus attachments will be nested inside.","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Customized Mode","type":"text"}]},{"type":"paragraph","content":[{"text":"Another option is to create the content JSON objects inside the mime message manually and set the attachments accordingly accordingly to the ","type":"text"},{"text":"RFC Mime Messages specification","type":"text","marks":[{"type":"link","attrs":{"href":"https://datatracker.ietf.org/doc/html/rfc2045"}}]},{"text":". This is the solution which is most flexible and highly customizable. But it is also the most complex approach.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Attaching content references","type":"text"}]},{"type":"paragraph","content":[{"text":"You can also use content references loaded into a pipeline scope like ","type":"text"},{"text":"vars","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"body","type":"text","marks":[{"type":"code"}]},{"text":" as source for attachments. For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - drive.read:\n path: \"contract.docx\"\n\n - notification.send:\n to: \"recipient@domain.tld\"\n subject: \"This is the contract\"\n message: \"Hello, attached you can find the contract for your reference.\"\n attachments: ${body}\n","type":"text"}]},{"type":"paragraph","content":[{"text":"In this example the file is first loaded (implicitly) to body using the command ","type":"text"},{"text":"drive.read","type":"text","marks":[{"type":"code"}]},{"text":" and then linked to the ","type":"text"},{"text":"attachments","type":"text","marks":[{"type":"code"}]},{"text":" parameter. You can place any ","type":"text"},{"text":"content reference","type":"text","marks":[{"type":"link","attrs":{"href":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2545320099"}}]},{"text":" as attachment.","type":"text"}]},{"type":"paragraph","content":[{"text":"Using this approach it is also possible to create the attachments dynamically on-the-fly in the pipeline (for example by using a template engine) and then add them finally to the email.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Templating Notifications","type":"text"}]},{"type":"paragraph","content":[{"text":"You can create dynamic notification texts and layouts using templating.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Using a Transformer","type":"text"},{"text":"","type":"text","marks":[{"type":"link","attrs":{"href":"https://pipeforce.github.io/docs/guides/messaging/email#using-a-transformer-command"}}]}]},{"type":"paragraph","content":[{"text":"You can use a transformer command like ","type":"text"},{"text":"transform.ftl","type":"text","marks":[{"type":"link","attrs":{"href":"https://pipeforce.github.io/docs/guides/guides/transformers/freemarker"}}]},{"text":" in order to render the message. For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"vars:\n name: \"Sam\"\n email: \"recipient@domain.tld\"\n\npipeline:\n\n - transform.ftl:\n template: |\n Hello ${vars.name},\n this is an email sent from a pipeline.\n Greetings\n\n - notification.send:\n to: ${vars.email}\n subject: \"This is for ${vars.name}\"\n message: ${body}","type":"text"}]},{"type":"paragraph","content":[{"text":"In this example, the message is rendered and then stored in the body using ","type":"text"},{"text":"transform.ftl","type":"text","marks":[{"type":"code"}]},{"text":". The command ","type":"text"},{"text":"notification.send","type":"text","marks":[{"type":"code"}]},{"text":" then picks up the rendered message from the body and uses it as email message.","type":"text"}]},{"type":"paragraph","content":[{"text":"And here is an example to load the template from the property store from location ","type":"text"},{"text":"global/app/myapp/template/email","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"vars:\n name: \"Sam\"\n email: \"recipient@domain.tld\"\n\npipeline:\n\n - transform.ftl:\n template: \"$uri:property:global/app/myapp/template/email\"\n\n - notification.send:\n to: ${vars.email}\n subject: \"This is for ${vars.name}\"\n message: ${body}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Embedded template URIs","type":"text"}]},{"type":"paragraph","content":[{"text":"It is also possible to embed the template references inside the mime notification using ","type":"text"},{"text":"PIPEFORCE URIs","type":"text","marks":[{"type":"link","attrs":{"href":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2548727819"}}]},{"text":". For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - notification.send:\n input: {\n \"headers\": {\n \"to\": [\"email1@domain.tld\", \"email2@domain.tld\"],\n \"subject\": \"$uri:template:global/app/my.app/template/subject\",\n }\n \"body\": {\n \"contentType\": \"multipart/mixed\",\n \"content\": [\n {\n \"contentType\": \"multipart/alternative\",\n \"content\": [\n {\n \"contentType\": \"text/plain; charset=UTF-8\",\n \"content\": \"$uri:template:global/app/my.app/template/body_txt\"\n },\n {\n \"contentType\": \"text/html; charset=UTF-8\",\n \"content\": \"$uri:template:global/app/my.app/template/body_html\"\n }\n ]\n }\n ]\n }\n }","type":"text"}]},{"type":"paragraph","content":[{"text":"In this example the ","type":"text"},{"text":"$uri:template:","type":"text","marks":[{"type":"code"}]},{"text":" URI is used. This will load the template from given location in property store and will render it using the template engine which fits the Content-Type of the property. By default, this is the ","type":"text"},{"text":"FreeMarker Template Engine","type":"text","marks":[{"type":"link","attrs":{"href":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2545647697"}}]},{"text":". Also all other ","type":"text"},{"text":"PIPEFORCE URIs","type":"text","marks":[{"type":"link","attrs":{"href":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2548727819"}}]},{"text":" are supported here instead such as these examples:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:property:path/to/property/with/template/content","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:pipeline:path/to/pipeline/which/creates/content/in/body","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"paragraph","content":[{"text":"The result of the URI call will be used as value for the notification. For example the email subject or body.","type":"text"}]},{"type":"paragraph","content":[{"text":"Any time the notification is sent, the elements of the mime message will be recursively scanned for existing ","type":"text"},{"text":"PIPEFORCE URIs","type":"text","marks":[{"type":"link","attrs":{"href":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2548727819"}}]},{"text":". In case one was found, it will be executed and in case it is supported, the current mime notification object will be auto-passed to the template and can be used there to access all relevant data from the mime message to render the template. Here is an example for a message rendered using the FreeMarker Template Language:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"plaintext"},"content":[{"text":"Hello ${to?join(\", \")},\nthis is an email with subject: ${subject}\nCheers","type":"text"}]},{"type":"paragraph","content":[{"text":"An here is an example doing this using a pipeline:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - body.set: |\n Hello ${body.to},\n this is an email with subject: ${subject}\n Cheers","type":"text"}]},{"type":"paragraph","content":[{"text":"For more details about the available fields provided to the template or pipeline, see below.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Template Model","type":"text"}]},{"type":"paragraph","content":[{"text":"Inside each template the ","type":"text"},{"text":"Mime Notification","type":"text","marks":[{"type":"strong"}]},{"text":" object will be automatically provided, which represents the current notifcation object as the template ","type":"text"},{"text":"root","type":"text","marks":[{"type":"strong"}]},{"text":" if it is a template (root = each field can be directly accessed) or as ","type":"text"},{"text":"body","type":"text","marks":[{"type":"strong"}]},{"text":" context if it is a pipeline call (body = each field can be accessed via the body context). See examples below.","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is an example to access a Mime Notification field inside a FreeMarker template as template root:","type":"text"}]},{"type":"codeBlock","content":[{"text":"Recipient username: ${allAddresses[0].user.username}","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is an example to access the same field inside a pipeline using the body context:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - body.set: \"Recipient username: ${body.allAddresses[0].user.username}\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Mime Notification","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Mime Notification","type":"text","marks":[{"type":"strong"}]},{"text":" object is provided inside each template or pipeline. It is the entry point to notification data and provides these fields which can be accessed inside a template or pipeline:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"headers","type":"text","marks":[{"type":"code"}]},{"text":" = A key-value map which contains all header values used to configure the notification.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":" = A list of resolved ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"Recipient","type":"text","marks":[{"type":"strong"}]},{"text":" objects.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":" = A list of resolved ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"Recipient ","type":"text","marks":[{"type":"strong"}]},{"text":"objects.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":" = A list of resolved ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"Recipient ","type":"text","marks":[{"type":"strong"}]},{"text":"objects.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"from","type":"text","marks":[{"type":"code"}]},{"text":" = The resolved from ","type":"text"},{"text":"Recipient","type":"text","marks":[{"type":"strong"}]},{"text":" object.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"subject","type":"text","marks":[{"type":"code"}]},{"text":" = Contains the (resolved) subject text.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"content","type":"text","marks":[{"type":"code"}]},{"text":" = Contains the nested mime ","type":"text"},{"text":"part","type":"text","marks":[{"type":"strong"}]},{"text":" objects as configured in the notification configuration.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"excludedAddresses","type":"text","marks":[{"type":"code"}]},{"text":" = A list of all resolved ","type":"text"},{"text":"Recipient","type":"text","marks":[{"type":"strong"}]},{"text":" objects excluded in this notification.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"allAddresses","type":"text","marks":[{"type":"code"}]},{"text":" = Combines all resolved ","type":"text"},{"text":"Recipient","type":"text","marks":[{"type":"strong"}]},{"text":" objects from ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":" into a single list and removes any duplicates.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"model","type":"text","marks":[{"type":"code"}]},{"text":" = The message model provided from external (for example from an event source). The structure of this model depends on the provider. See the event topics for example to learn about the structure of this mode.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"uuid","type":"text","marks":[{"type":"code"}]},{"text":" = The unique id of this notification, if set.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"attachments","type":"text","marks":[{"type":"code"}]},{"text":" = A list of ","type":"text"},{"text":"Mime","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Part","type":"text","marks":[{"type":"strong"}]},{"text":" objects extracted from the content body, defining the attachments of this notification.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Recipient","type":"text"}]},{"type":"paragraph","content":[{"text":"The structure of a notification ","type":"text"},{"text":"Recipient","type":"text","marks":[{"type":"strong"}]},{"text":" object is like this:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"name","type":"text","marks":[{"type":"code"}]},{"text":" = The display name of the recipient.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"locale","type":"text","marks":[{"type":"code"}]},{"text":" = The locale of the recipient to be used for this notification.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"address","type":"text","marks":[{"type":"code"}]},{"text":" = The address uri of the recipient.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"plainAddress","type":"text","marks":[{"type":"code"}]},{"text":" = The plain address without any URI prefixes or query parameters.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"channel","type":"text","marks":[{"type":"code"}]},{"text":" = The channel of this recipient (for example ","type":"text"},{"text":"email","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"slack","type":"text","marks":[{"type":"code"}]},{"text":", ...)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"user","type":"text","marks":[{"type":"code"}]},{"text":" = In case the recipient address is related to a user in IAM, this field contains information about the user. If no IAM user is linked, this field is null. The child values of the user if exists, are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"createdTimestamp","type":"text","marks":[{"type":"code"}]},{"text":" = The unix timestamp in millis when this user was created.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"displayName","type":"text","marks":[{"type":"code"}]},{"text":" = The firstName + lastName if exists, otherwise the email. If also email doesnt exist, returns the uuid of the user (not username for security reasons).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"email","type":"text","marks":[{"type":"code"}]},{"text":" = The email address of the user (same as address of recipient.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"emailAndDisplayName","type":"text","marks":[{"type":"code"}]},{"text":" = The email and display name in the format: firstNameAndLastName (email). If email doesnt exist, returns only display name. If display name doesnt exist, returns only email. Returns empty string if none exists.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"enabled","type":"text","marks":[{"type":"code"}]},{"text":" = Is this user enabled in the system?","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"firstAndLastName","type":"text","marks":[{"type":"code"}]},{"text":" = Returns a string of format: ","type":"text"},{"text":"firstName lastName","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"firstName","type":"text","marks":[{"type":"code"}]},{"text":" = The first name of the user if set.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"groups","type":"text","marks":[{"type":"code"}]},{"text":" = A list of group names, the user is member of.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"lastName =","type":"text","marks":[{"type":"code"}]},{"text":" The last name of the if set.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"locale","type":"text","marks":[{"type":"code"}]},{"text":" = The preferred locale (language) of the user.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"username","type":"text","marks":[{"type":"code"}]},{"text":" = The unique username of the user.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"uuid","type":"text","marks":[{"type":"code"}]},{"text":" = The unique id of the user.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"zone","type":"text","marks":[{"type":"code"}]},{"text":" = The preferred (time) zone of the user.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Mime Part","type":"text"}]},{"type":"paragraph","content":[{"text":"The structure of a notification ","type":"text"},{"text":"Mime Part","type":"text","marks":[{"type":"strong"}]},{"text":" is like this (","type":"text"},{"text":"also see official MIME specification for this","type":"text","marks":[{"type":"link","attrs":{"href":"https://datatracker.ietf.org/doc/html/rfc2045"}}]},{"text":"):","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"contentType","type":"text","marks":[{"type":"code"}]},{"text":" = The MIME content type of the content value.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"contentDisposition","type":"text","marks":[{"type":"code"}]},{"text":" = The disposition header as defined in the MIME specification.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"contentTransferEncoding","type":"text","marks":[{"type":"code"}]},{"text":" = The transfer encoding as defined in the MIME specification.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"content","type":"text","marks":[{"type":"code"}]},{"text":" = The content of the part which can be one of:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A PIPEFORCE URI if ","type":"text"},{"text":"contentTransferEncoding","type":"text","marks":[{"type":"code"}]},{"text":" is set to ","type":"text"},{"text":"outbound-url","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A base64 encoded string if ","type":"text"},{"text":"contentTransferEncoding","type":"text","marks":[{"type":"code"}]},{"text":" is set to ","type":"text"},{"text":"base64","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A text value with format given by ","type":"text"},{"text":"contentType","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A list of nested Part’s in case ","type":"text"},{"text":"contentType","type":"text","marks":[{"type":"code"}]},{"text":" is ","type":"text"},{"text":"multipart/mixed","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Addresses and address resolving","type":"text"}]},{"type":"paragraph","content":[{"text":"In the headers section of a mime notification you can declare the addresses of the recipients where the notification must be send to. Here is an example how to do this directly inside the mime notification JSON:","type":"text"}]},{"type":"codeBlock","content":[{"text":"pipeline:\n - notification.send:\n input: {\n \"headers\": {\n \"to\": [\"email1@domain.tld\", \"email2@domain.tld\"],\n \"cc\": [\"email3@domain.tld\"],\n \"bcc\": [\"email4@domain.tld\"],\n \"subject\": \"This is the subject\",\n }\n \"body\": {\n \"contentType\": \"text/plain\",\n \"content\": \"This is the plain text body.\"\n }\n }","type":"text"}]},{"type":"paragraph","content":[{"text":"As an alternative you can also use the simple mode by declaring them as parameters directly on the command:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - notification.send:\n to: [\"email1@domain.tld\", \"email2@domain.tld\"]\n cc: \"email3@domain.tld\"\n bcc: \"email4@domain.tld\"\n subject: \"This is the subject\"\n message: \"This is the plain text body.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"These address parameters will be converted to a mime notification JSON and placed in its header section for you.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Addresses prefixed with $uri:","type":"text"}]},{"type":"paragraph","content":[{"text":"By default all addresses are assumed to be valid email addresses. But you can also use other address types to send the notification to a different channel. In case an address is not an email address, it always must be prefixed with ","type":"text"},{"text":"$uri:","type":"text","marks":[{"type":"code"}]},{"text":" . Here is an example to use a Slack channel as target address instead:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - notification.send:\n to: \"$uri:slack:mychatgroup\"\n subject: \"This is the subject\"\n message: \"This is the plain text body.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"In this example, the message will be send to a Slack channel instead of via email. You can also combine different addresses of different types like this example shows:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - notification.send:\n to: [\"$uri:slack:mychatgroup\", \"email1@domain.tld\"]\n subject: \"This is the subject\"\n message: \"This is the plain text body.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"In this example the notification will be rendered as a Slack message and send to the Slack channel with name ","type":"text"},{"text":"mychatgroup","type":"text","marks":[{"type":"code"}]},{"text":" and additionally it will be rendered as email message and send to the email address ","type":"text"},{"text":"email1@domain.tld","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Final and expandable addresses","type":"text"}]},{"type":"paragraph","content":[{"text":"There can be ","type":"text"},{"text":"final","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"expandable","type":"text","marks":[{"type":"strong"}]},{"text":" addresses:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Final address: ","type":"text","marks":[{"type":"strong"}]},{"text":"The address can be used as it is by a channel to deliver the message. For example an email address.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Expandable address:","type":"text","marks":[{"type":"strong"}]},{"text":" The address needs to resolved (expanded) to one or more final addresses first, before it can be used by a channel to deliver the notification. For example an address referring to a user in IAM must first be expanded (resolved) to the user’s email address before the notification can be send.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Here is an example how such a resolving could look like:","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"drawio","parameters":{"macroParams":{"mVer":{"value":"2"},"zoom":{"value":"1"},"simple":{"value":"0"},"inComment":{"value":"0"},"custContentId":{"value":"2768699406"},"pageId":{"value":"2767224839"},"lbox":{"value":"1"},"diagramDisplayName":{"value":"Untitled Diagram-1711640585616.drawio"},"contentVer":{"value":"2"},"revision":{"value":"2"},"baseUrl":{"value":"https://logabit.atlassian.net/wiki"},"diagramName":{"value":"Untitled Diagram-1711640585616.drawio"},"pCenter":{"value":"0"},"width":{"value":"871"},"links":{"value":""},"tbstyle":{"value":""},"height":{"value":"390.5"}},"macroMetadata":{"macroId":{"value":"1d4c081d-b481-4e2f-ac1c-beab9b636692"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"image","data":{"url":"https://ac.draw.io/connectImage?mVer=2&zoom=1&simple=0&inComment=0&custContentId=2768699406&pageId=2767224839&lbox=1&diagramDisplayName=Untitled+Diagram-1711640585616.drawio&contentVer=2&revision=2&baseUrl=https%3A%2F%2Flogabit.atlassian.net%2Fwiki&diagramName=Untitled+Diagram-1711640585616.drawio&pCenter=0&width=871&links=&tbstyle=&height=390.5"}}],"title":"draw.io Diagram"}},"localId":"063e9bfc-c960-4a04-8e73-22ca41fa2782"}},{"type":"paragraph","content":[{"text":" Expandable addresses could also be recursive.","type":"text"}]},{"type":"paragraph","content":[{"text":"The resolving (expanding) is automatically done by the notification framework.","type":"text"}]},{"type":"paragraph","content":[{"text":"Some notes about this example:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A","type":"text","marks":[{"type":"strong"}]},{"text":": Final addresses. They will be used to send the notification directly to the channels.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"B","type":"text","marks":[{"type":"strong"}]},{"text":": The supervisor will get this notification via its default email.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"C","type":"text","marks":[{"type":"strong"}]},{"text":": Any user who is member of group ","type":"text"},{"text":"sales","type":"text","marks":[{"type":"code"}]},{"text":" will get this notification via its preferred notification channel. In this example, this is user ","type":"text"},{"text":"manager1","type":"text","marks":[{"type":"code"}]},{"text":" and his notification channels from IAM are ","type":"text"},{"text":"sales1@company.tld","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"private1@mail.tld","type":"text","marks":[{"type":"code"}]},{"text":" .","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"D","type":"text","marks":[{"type":"strong"}]},{"text":": The group ","type":"text"},{"text":"sales","type":"text","marks":[{"type":"code"}]},{"text":" contains another group ","type":"text"},{"text":"admins","type":"text","marks":[{"type":"code"}]},{"text":" and therefore all members of this role will additionally get the notification via their preferred address. ","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When the notification is processed, all groups and users will be resolved and the preferred channel will be used to send the notification.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Handling address duplicates","type":"text"}]},{"type":"paragraph","content":[{"text":"Duplicate addresses which appear ","type":"text"},{"text":"after","type":"text","marks":[{"type":"strong"}]},{"text":" expanding will be removed (for example because a user is member of multiple groups or roles configured for the notification, so his address is used only once).","type":"text"}]},{"type":"paragraph","content":[{"text":"In case the same addresses is used in ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":", then the address in the lowest visibility will be kept. The visibility is like this (from lowest to highest):","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"bcc","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"to","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"cc","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"paragraph","content":[{"text":"So for example if the same address is given in ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":" it will be removed from ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":" and only kept in ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":". Another example: If the same address is given in ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":", it will be kept in ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":" and removed from ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":". And if the same address is given in ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":", it will be kept in ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":" and removed from ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":". And so on.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"$uri:email:","type":"text"}]},{"type":"paragraph","content":[{"text":"This ","type":"text"},{"text":"final","type":"text","marks":[{"type":"strong"}]},{"text":" address will send the notification via email. The format is like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:email:","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:email:foo.bar@logabit.com","type":"text"}]},{"type":"paragraph","content":[{"text":"This is an alternative to not using the prefix at all. So this is also a valid email address:","type":"text"}]},{"type":"codeBlock","content":[{"text":"foo.bar@logabit.com","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"$uri:user:","type":"text"}]},{"type":"paragraph","content":[{"text":"This ","type":"text"},{"text":"expandable","type":"text","marks":[{"type":"strong"}]},{"text":" address will lookup the user with given username in IAM (user management) and be converted to the registered target address of the user which is an email address by default. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The format is like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:user:","type":"text"}]},{"type":"paragraph","content":[{"text":"Whereas ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" must be an enabled and exiting user in IAM with is username. ","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:user:maxhuber","type":"text"}]},{"type":"paragraph","content":[{"text":"In case the user is disabled or doesn’t exist, this address will be ignored and removed from the address fields.","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"paragraph","content":[{"text":"Let’s assume as default address of the user ","type":"text"},{"text":"maxhuber","type":"text","marks":[{"type":"code"}]},{"text":" in IAM the email address ","type":"text"},{"text":"foo.bar@logabit.com","type":"text","marks":[{"type":"code"}]},{"text":" is configured, then an address field like this:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"3c09565e-ca03-4339-9380-955fe9c02717"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[85.0]},"content":[{"type":"paragraph","content":[{"text":"\"to\"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[675.0]},"content":[{"type":"paragraph","content":[{"text":"[\"$uri:user:maxhuber\"]","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Will be resolved to this:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"81cb5d8e-cda4-4dfc-beec-1a5b77be14c1"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[85.0]},"content":[{"type":"paragraph","content":[{"text":"\"to\"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[675.0]},"content":[{"type":"paragraph","content":[{"text":"[\"$uri:email:foo.bar@logabit.com\"]","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"$uri:group:","type":"text"}]},{"type":"paragraph","content":[{"text":"This ","type":"text"},{"text":"expandable","type":"text","marks":[{"type":"strong"}]},{"text":" address will lookup a group with given name in IAM (user management) and it will be resolved to the default addresses of all user members of this group.","type":"text"}]},{"type":"paragraph","content":[{"text":"The format is like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:group:","type":"text"}]},{"type":"paragraph","content":[{"text":"Whereas ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" must be an enabled and existing group in IAM with this group name. For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:group:sales","type":"text"}]},{"type":"paragraph","content":[{"text":"In case the group is disabled or doesn’t exist, this address will be ignored and removed from the address fields. ","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"paragraph","content":[{"text":"Let’s assume there is a group ","type":"text"},{"text":"sales","type":"text","marks":[{"type":"code"}]},{"text":" in IAM with with these member users and their default target addresses configured in IAM:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"eca49f4e-66b6-4c35-a2de-d279e7815f48"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Username","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Target Address","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"teamlead","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"teamlead@mail.tld","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"user1","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"$uri:slack:mychannel","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"user2","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"$uri:email:user2@mail.tld","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Then, an address field like this:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"66d5274f-5894-4cea-9288-31af344660d7"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[85.0]},"content":[{"type":"paragraph","content":[{"text":"\"to\"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[675.0]},"content":[{"type":"paragraph","content":[{"text":"[\"$uri:group:sales\"]","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Will be expanded (resolved) to this:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"f4fb109c-c498-4ee4-bbb9-f8f22e22b14f"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[85.0]},"content":[{"type":"paragraph","content":[{"text":"\"to\"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[675.0]},"content":[{"type":"paragraph","content":[{"text":"[\"$uri:email:teamlead@mail.tld\", \"$uri:slack:mychannel\", \"$uri:email:user2@mail.tld\"]","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"$uri:slack:","type":"text"}]},{"type":"paragraph","content":[{"text":"This ","type":"text"},{"text":"final","type":"text","marks":[{"type":"strong"}]},{"text":" address will send the notification to a Slack channel as configured by the connection config id.","type":"text"}]},{"type":"paragraph","content":[{"text":"The format is like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:slack:","type":"text"}]},{"type":"paragraph","content":[{"text":"Whereas ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" must be an id of a valid and enabled connection configuration. ","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:slack:sales-channel","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"$uri:teams:","type":"text"}]},{"type":"paragraph","content":[{"text":"This ","type":"text"},{"text":"final","type":"text","marks":[{"type":"strong"}]},{"text":" address will send the notification to a Microsoft Teams channel as configured by the connection config id.","type":"text"}]},{"type":"paragraph","content":[{"text":"The format is like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:teams:","type":"text"}]},{"type":"paragraph","content":[{"text":"Whereas ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" must be an id of a valid and enabled connection configuration. ","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:teams:sales-team","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"$uri:message-route:","type":"text"}]},{"type":"paragraph","content":[{"text":"This is a ","type":"text"},{"text":"final","type":"text","marks":[{"type":"strong"}]},{"text":" address: It will forward the message to the message broker using the given routing key.","type":"text"}]},{"type":"paragraph","content":[{"text":"The format is like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:message-route:","type":"text"}]},{"type":"paragraph","content":[{"text":"Whereas ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" is the target routing key where the message must be forwarded to. The mime notification headers will be set as message headers and the body will be serialized as JSON into the playload of the message.","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:message-route:security_audit_queue","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"$uri:pipeline:","type":"text"}]},{"type":"paragraph","content":[{"text":"This ","type":"text"},{"text":"expandable","type":"text","marks":[{"type":"strong"}]},{"text":" address will call the pipeline given by path, puts the mime notification into its body and executes it. It expects a JSON array of addresses to be returned, all starting with prefix ","type":"text"},{"text":"$uri:","type":"text","marks":[{"type":"code"}]},{"text":". Otherwise, the address will be ignored. These addresses will then replace the ","type":"text"},{"text":"$uri:pipeline:","type":"text","marks":[{"type":"code"}]},{"text":" address in the fields.","type":"text"}]},{"type":"paragraph","content":[{"text":"The format is like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:pipeline:","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:pipeline:global/app/my.app/pipeline/dynamic-addresses","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"dynamic-addresses","type":"text","marks":[{"type":"code"}]},{"text":" pipeline could look like this example to return addresses dynamically:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - body.set:\n value: [\"$uri:email:address1@mail.tld\", \"$uri:user:someusername\"]","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"$uri:property:","type":"text"}]},{"type":"paragraph","content":[{"text":"This ","type":"text"},{"text":"expandable","type":"text","marks":[{"type":"strong"}]},{"text":" address will load the property at given path and expects the value to be a JSON array containing the addresses to be returned.","type":"text"}]},{"type":"paragraph","content":[{"text":"The format is like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:property:","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$uri:property:global/app/my.app/data/my-addresses","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"my-addresses","type":"text","marks":[{"type":"code"}]},{"text":" pipeline could look like this example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"[\"$uri:email:address1@mail.tld\", \"$uri:user:someusername\"]","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"$uri:wf- (workflow addresses)","type":"text"}]},{"type":"paragraph","content":[{"text":"In case a push event is a workflow event (see ","type":"text"},{"text":"pipeforce.event.workflow.#","type":"text","marks":[{"type":"link","attrs":{"href":"https://logabit.atlassian.net/wiki/spaces/PA/pages/3234168924"}}]},{"text":"), these additional address variables can be used in TO, CC and BCC fields to refer to data from the event message:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:wf-authenticated-user","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"Returns the ","type":"text"},{"text":"$uri:user:","type":"text","marks":[{"type":"code"}]},{"text":" of the user who was logged-in at the time of this event and potentially has initiated this event.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:wf-process-involved-users","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"Returns the ","type":"text"},{"text":"$uri:user:","type":"text","marks":[{"type":"code"}]},{"text":" of all users involved in the workflow process.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:wf-started-by","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"Returns the ","type":"text"},{"text":"$uri:user:","type":"text","marks":[{"type":"code"}]},{"text":" of the user who started the workflow.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:wf-task-candidate-groups","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"Returns the ","type":"text"},{"text":"$uri:group:","type":"text","marks":[{"type":"code"}]},{"text":" names of all groups which are set as candidate group of given task. In case there is no candidate group set, the address variable will be removed from all address fields.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:wf-task-candidate-users","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"Returns the ","type":"text"},{"text":"$uri:user:","type":"text","marks":[{"type":"code"}]},{"text":" names of all users which are set as candidate users of given task. In case there is no candidate user set, the address variable will be removed from all address fields.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:wf-task-assignee","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"Returns the ","type":"text"},{"text":"$uri:user:","type":"text","marks":[{"type":"code"}]},{"text":" of the user who is set as assignee on given workflow task. In case there is no taskAssignee set, the address variable will be removed from all address fields.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:wf-task-owner","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"Returns the ","type":"text"},{"text":"$uri:user:","type":"text","marks":[{"type":"code"}]},{"text":" of the user who is set as assignee on the given workflow task. In case there is no taskOwner set, the address variable will be removed from all address fields.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:author","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"In case the event is related to a comment creation, returns the ","type":"text"},{"text":"$uri:user:","type":"text","marks":[{"type":"code"}]},{"text":" of the user who created the comment. This is also true for comments created outside of workflow related events.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Duplicate addresses will always be removed.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resolving of expandable addresses","type":"text"}]},{"type":"paragraph","content":[{"text":"Expandable","type":"text","marks":[{"type":"strong"}]},{"text":" addresses are resolved (expanded) recursively until the ","type":"text"},{"text":"final","type":"text","marks":[{"type":"strong"}]},{"text":" address appears. So for example an expandable address given like this:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"aaad2e5c-dc83-4714-98a7-052e5b89c98e"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[85.0]},"content":[{"type":"paragraph","content":[{"text":"\"to\"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[675.0]},"content":[{"type":"paragraph","content":[{"text":"[\"$uri:pipeline:global/app/my.app/pipeline/my-adresses\"]","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Could return and resolve to:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"678f36f3-a2aa-4096-a6e4-8efff929d0d3"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[85.0]},"content":[{"type":"paragraph","content":[{"text":"\"to\"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[675.0]},"content":[{"type":"paragraph","content":[{"text":"[\"$uri:email:user1@logabit.com\", \"$uri:group:sales\"]","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Which in term could resolve to this in the next recursion:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"ca8a85d6-14e3-42b6-bece-ecf1950c6695"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[85.0]},"content":[{"type":"paragraph","content":[{"text":"\"to\"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[675.0]},"content":[{"type":"paragraph","content":[{"text":"[\"$uri:email:user1@logabit.com\", \"$uri:user:user2\", \"$uri:user:user3\", \"$uri:user:user4\"]","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Which resolves to these final addresses:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"ab07d8b7-959b-4d3f-a379-5246d6cf1acd"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[85.0]},"content":[{"type":"paragraph","content":[{"text":"\"to\"","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[675.0]},"content":[{"type":"paragraph","content":[{"text":"[\"$uri:email:user1@logabit.com\", \"$uri:email:user2@logabit.com\", \"$uri:email:user3@logabit.com\", \"$uri:email:user4@logabit.com\"]","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Excluding addresses","type":"text"}]},{"type":"paragraph","content":[{"text":"It is possible to exclude certain addresses from a mime message. To do so, you can use the custom header ","type":"text"},{"text":"x-pipeforce-exclude-addresses","type":"text","marks":[{"type":"code"}]},{"text":" and specify the addresses to be excluded. For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"headers\": {\n \"x-pipeforce-exclude-addresses\": [\"$uri:group:vacation\"]\n \"to\": [\"$uri:group:sales\"],\n \"subject\": \"New lead\",\n }\n \"body\": {\n \"contentType\": \"text/plain\",\n \"content\": \"Hi, a new lead was created.\"\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"In this example, the ","type":"text"},{"text":"New lead","type":"text","marks":[{"type":"code"}]},{"text":" notification will be send to all members of group ","type":"text"},{"text":"sales","type":"text","marks":[{"type":"code"}]},{"text":" excluding those users also in group ","type":"text"},{"text":"vacation","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Exclude addresses can be ","type":"text"},{"text":"final","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"expandable","type":"text","marks":[{"type":"strong"}]},{"text":" addresses.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Multi-Language Notifications (i18n)","type":"text"}]},{"type":"paragraph","content":[{"text":"The notification framework supports multi language notifications. This means a notification can be send in different languages to multiple recipients. The framework handles the way how the templates related to the selected language will be loaded and clusters the notifications based on the selected language (locale). ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"How to enable it","type":"text"}]},{"type":"paragraph","content":[{"text":"By default i18 is turned-off. In order to enable multi-language (i18n) support, you have to set the header ","type":"text"},{"text":"x-pipeforce-multilang","type":"text","marks":[{"type":"code"}]},{"text":" to ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":" in your notification configuration:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"headers\": {\n \"x-pipeforce-multilang\": true,\n ...\n }\n ...\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"How it works","type":"text"}]},{"type":"paragraph","content":[{"text":"The main concept behind i18n support in notifications is that any ","type":"text"},{"text":"$uri:template","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"$uri:property","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"$uri:pipeline","type":"text","marks":[{"type":"code"}]},{"text":" which is used in subject or body of the notification will automatically be suffixed with the selected locale (= language key): For example, if you use the URI ","type":"text"},{"text":"$uri:template:global/app/com.acme.myapp/mytemplate","type":"text","marks":[{"type":"code"}]},{"text":" inside your notification configuration like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"headers\": {\n \"to\": [\"email1@domain.tld\", \"email2@domain.tld\"],\n \"subject\": \"This is the subject\",\n }\n \"body\": {\n \"contentType\": \"text/plain\",\n \"content\": \"$uri:template:global/app/com.acme.myapp/mytemplate\"\n }\n }","type":"text"}]},{"type":"paragraph","content":[{"text":"… and the locale ","type":"text"},{"text":"de","type":"text","marks":[{"type":"code"}]},{"text":" (german) is selected, the URI will automatically become ","type":"text"},{"text":"$uri:template:global/app/com.acme.myapp/mytemplate_de","type":"text","marks":[{"type":"code"}]},{"text":": It will be prefixed with ","type":"text"},{"text":"_de","type":"text","marks":[{"type":"code"}]},{"text":" so the template specific to german language can be loaded. And in case the locale ","type":"text"},{"text":"en","type":"text","marks":[{"type":"code"}]},{"text":" (english) is selected, this prefixed URI will be loaded instead: ","type":"text"},{"text":"$uri:template:global/app/com.acme.myapp/mytemplate_en","type":"text","marks":[{"type":"code"}]},{"text":" (the suffix ","type":"text"},{"text":"_en","type":"text","marks":[{"type":"code"}]},{"text":" is appended). This way you can organize your templates in the property store in a clear way. For example it could look like this:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"global/app/com.acme.myapp/template/","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"mytemplate_de","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"mytemplate_en","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"mytemplate_fr","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"mytemplate_sk","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Here are the steps, how this all works together:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It will look for a query param ","type":"text"},{"text":"?locale=","type":"text","marks":[{"type":"code"}]},{"text":" in each address in ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":" fields. ","type":"text"},{"type":"hardBreak"},{"text":"For example: ","type":"text"},{"text":"$uri:email:foo@bar.tld?locale=de","type":"text","marks":[{"type":"code"}]},{"text":". If no locale exists it will use ","type":"text"},{"text":"en","type":"text","marks":[{"type":"code"}]},{"text":" as default.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the address is an IAM address like ","type":"text"},{"text":"$uri:group:","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"$uri:user:","type":"text","marks":[{"type":"code"}]},{"text":" it will use the value of user attribute ","type":"text"},{"text":"locale","type":"text","marks":[{"type":"code"}]},{"text":" from IAM for the locale, if exists. Otherwise, it will fallback to ","type":"text"},{"text":"en","type":"text","marks":[{"type":"code"}]},{"text":" as default. If both are given (query param and locale attribute in IAM), the query param will have precedence.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It will split a notification to multiple notifications for each new language and will manage to split also addresses according to these languages. For example if there are these TO addresses set: ","type":"text"},{"text":"$uri:email:my@mail.tld?locale=de, $uri:email:another@mail.tld?locale=en","type":"text","marks":[{"type":"code"}]},{"text":" this means ","type":"text"},{"text":"two","type":"text","marks":[{"type":"strong"}]},{"text":" emails will be rendered and send: One with ","type":"text"},{"text":"de","type":"text","marks":[{"type":"code"}]},{"text":" as language with german text in subject and body and one with english text. Finally, there will be two emails: The DE one is sent to ","type":"text"},{"text":"my@mail.tld","type":"text","marks":[{"type":"code"}]},{"text":" and the EN one sent to ","type":"text"},{"text":"another@mail.tld","type":"text","marks":[{"type":"code"}]},{"text":". The same is true for addresses in ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"As already mentioned above, any ","type":"text"},{"text":"$uri:template","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"$uri:property","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"$uri:pipeline","type":"text","marks":[{"type":"code"}]},{"text":" which is used in subject and body of the notification configuration will automatically be suffixed with the selected locale. So for example ","type":"text"},{"text":"$uri:template:global/app/com.acme.myapp/mytemplate","type":"text","marks":[{"type":"code"}]},{"text":" will become ","type":"text"},{"text":"$uri:template:global/app/com.acme.myapp/mytemplate_de","type":"text","marks":[{"type":"code"}]},{"text":" in case the detected language (locale) is set to ","type":"text"},{"text":"de","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Additionally, the detected language (locale) will be set as ","type":"text"},{"text":"Content-Lang","type":"text","marks":[{"type":"code"}]},{"text":" header (which is a standard MIME header) so it can be used in the templates and/or at target client side as well.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Static suffix / disable suffixing","type":"text"}]},{"type":"paragraph","content":[{"text":"In some situations, suffixing the template resource path is ","type":"text"},{"text":"not wanted ","type":"text","marks":[{"type":"strong"}]},{"text":"or a static suffix must be used for all of such resources. For this, you can set the header ","type":"text"},{"text":"x-pipeforce-multilang-suffix","type":"text","marks":[{"type":"code"}]},{"text":" to a static suffix. If this is set, it will be used and the calculated suffixes from the language (for example ","type":"text"},{"text":"_en","type":"text","marks":[{"type":"code"}]},{"text":") will be ignored.","type":"text"}]},{"type":"paragraph","content":[{"text":"In case you don’t want to use suffixes at all, set this header to empty string ","type":"text"},{"text":"\"\"","type":"text","marks":[{"type":"code"}]},{"text":". Then, always the template resource without suffix will be loaded. You can then add language specific logics inside your template by using the ","type":"text"},{"text":"Content-Lang","type":"text","marks":[{"type":"code"}]},{"text":" header which is also provided into the template.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Multi-Channel Notifications ","type":"text"}]},{"type":"paragraph","content":[{"text":"The notification framework also supports sending a notification to different channels. This way it is possible beside via email, the same notification can be send to a Slack channel, via SMS and Teams for example. For each channel, different templates can be provided in order to adjust the format of the message so it fits the target channel.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"How to enable it","type":"text"}]},{"type":"paragraph","content":[{"text":"By default multi-channel support is disabled. In order to enable multi-channel support, you have to set the header ","type":"text"},{"text":"x-pipeforce-multichannel","type":"text","marks":[{"type":"code"}]},{"text":" to ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":" in your notification configuration:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"headers\": {\n \"x-pipeforce-multichannel\": true,\n ...\n }\n ...\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"How it works","type":"text"}]},{"type":"paragraph","content":[{"text":"If multi-channel support is enabled, the framework will handle a notification similar to the multi-language approach:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It will look for the final addresses in the address uri. For example:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:email: → ","type":"text"},{"text":"email","type":"text","marks":[{"type":"code"}]},{"text":" channel","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:slack: → ","type":"text"},{"text":"slack","type":"text","marks":[{"type":"code"}]},{"text":" channel","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:teams: → ","type":"text"},{"text":"teams","type":"text","marks":[{"type":"code"}]},{"text":" channel","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"$uri:sms → ","type":"text"},{"text":"sms","type":"text","marks":[{"type":"code"}]},{"text":" channel","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"aso.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It will split a single notification to multiple notification messages: For each new channel and will manage to split also addresses according to these channels. For example if there are these TO addresses set: ","type":"text"},{"text":"$uri:email:my@mail.tld?locale=de, $uri:slack:mygroup","type":"text","marks":[{"type":"code"}]},{"text":" this means two notifications will be rendered and send: One as email and the other one as Slack message. The same is true for addresses in CC and BCC.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Any ","type":"text"},{"text":"$uri:template","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"$uri:property","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"$uri:pipeline","type":"text","marks":[{"type":"code"}]},{"text":" which is used in subject and body of the notification will automatically be suffixed with the selected channel. So for example ","type":"text"},{"text":"$uri:template:mytemplate","type":"text","marks":[{"type":"code"}]},{"text":" will become ","type":"text"},{"text":"$uri:template:mytemplate_slack","type":"text","marks":[{"type":"code"}]},{"text":" in case the channel is set to ","type":"text"},{"text":"slack ","type":"text","marks":[{"type":"code"}]},{"text":"via address. This way, different templates can be provided in the property store and the notification framework will pick-up the one which belongs to the selected channel.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Additionally, the detected channel will be set as ","type":"text"},{"text":"x-pipeforce-channel","type":"text","marks":[{"type":"code"}]},{"text":" header so it can be used in the templates as well.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"In case both multi-lang and multi-channel are enabled for the notification, the channel name and the selected locale will be suffixed as ","type":"text"},{"text":"__","type":"text","marks":[{"type":"code"}]},{"text":". For example ","type":"text"},{"text":"$uri:template:mytemplate","type":"text","marks":[{"type":"code"}]},{"text":" becomes ","type":"text"},{"text":"$uri:template:mytemplate_slack_de","type":"text","marks":[{"type":"code"}]},{"text":" in case the detected channel from address is ","type":"text"},{"text":"slack","type":"text","marks":[{"type":"code"}]},{"text":" and the detected language is ","type":"text"},{"text":"de","type":"text","marks":[{"type":"code"}]},{"text":". This way you can create template specific to channel + language.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Static suffix / disable suffixing","type":"text"}]},{"type":"paragraph","content":[{"text":"In some situations, suffixing the template resource path is not wanted or a static suffix must be used for all of such resources. For this, you can set the header ","type":"text"},{"text":"x-pipeforce-multichannel-suffix","type":"text","marks":[{"type":"code"}]},{"text":" to a static suffix. If this is set, it will be used and the calculated suffixes from the channel (for example ","type":"text"},{"text":"_email","type":"text","marks":[{"type":"code"}]},{"text":") will be ignored.","type":"text"}]},{"type":"paragraph","content":[{"text":"In case you don’t want to use suffixes at all, set this header to empty string ","type":"text"},{"text":"\"\"","type":"text","marks":[{"type":"code"}]},{"text":". Then, always the template resource without suffix will be loaded. You can then add channel specific logics inside your template by using the ","type":"text"},{"text":"x-pipeforce-channel","type":"text","marks":[{"type":"code"}]},{"text":" header which is also provided into the template.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Personalized Notifications","type":"text"}]},{"type":"paragraph","content":[{"text":"Lets a assume you have a list of recipient addresses configured in your notification configuration like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"headers\": {\n \"to\": [\"$uri:user:someUser1\", \"$uri:user:someUser2\"]\n },\n ...\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"… and instead of sending the same static email to all of these recipients you would like to generate and send individual text messages for each. ","type":"text"}]},{"type":"paragraph","content":[{"text":"So for example ","type":"text"},{"text":"someUser1","type":"text","marks":[{"type":"code"}]},{"text":" should get this email text:","type":"text"}]},{"type":"codeBlock","content":[{"text":"Hello someUser1,\nthis is a personlized email for you.","type":"text"}]},{"type":"paragraph","content":[{"text":"… and ","type":"text"},{"text":"someUser2","type":"text","marks":[{"type":"code"}]},{"text":" should get this email text:","type":"text"}]},{"type":"codeBlock","content":[{"text":"Hello someUser2,\nthis is a personlized email for you.","type":"text"}]},{"type":"paragraph","content":[{"text":"To do so, you have to set the header ","type":"text"},{"text":"x-pipeforce-personalized","type":"text","marks":[{"type":"code"}]},{"text":" to ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"headers\": {\n \"x-pipeforce-personalized\": true,\n \"to\": [\"$uri:user:someUser1\", \"$uri:user:someUser2\"]\n },\n ...\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"In this case for each recipient the templating rendering is called again so the content can be personalized then. The ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":" header will always be set to the personalized recipient and ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":" will be deleted. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Inside the template you can then access the personalized recipient by accessing the ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":" header or by calling ","type":"text"},{"text":"allAddresses[0]","type":"text","marks":[{"type":"code"}]},{"text":". Here is an example how such a template could look like:","type":"text"}]},{"type":"codeBlock","content":[{"text":"<#assign recipient = allAddresses[0]>\nHello ${recipient.name},\nthis is a personlized email for you.","type":"text"}]},{"type":"paragraph","content":[{"text":"This will be repeated for every recipient, regardless whether it is set on ","type":"text"},{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]},{"type":"paragraph","content":[{"text":"Finally, the text result of each template rendering will be send as individual message.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Push Notifications","type":"text"}]},{"type":"paragraph","content":[{"text":"Push notifications are system and business events, a user can subscribe to. Any time there is a match, such an event is automatically converted to a notification and will be send to the registered user's preferred communication channels like email or chat group for example. ","type":"text"}]},{"type":"paragraph","content":[{"text":"A push notification always starts with a message sent with routing key ","type":"text"},{"text":"pipeforce.event.#","type":"text","marks":[{"type":"code"}]},{"text":". All messages having a routing key starting with this prefix will be stored in the ","type":"text"},{"text":"pipeforce_push","type":"text","marks":[{"type":"code"}]},{"text":" queue.","type":"text"}]},{"type":"paragraph","content":[{"text":"By default the ","type":"text"},{"text":"pipeforce_push","type":"text","marks":[{"type":"code"}]},{"text":" queue has these restrictions:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Max. number of messages in queue: ","type":"text"},{"text":"20.000","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Max. time to life: ","type":"text"},{"text":"48 hours","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Max. size of all messages in queue: ","type":"text"},{"text":"100 MB","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"As soon as one of these restrictions are met, ","type":"text"},{"text":"oldest","type":"text","marks":[{"type":"underline"},{"type":"strong"}]},{"text":" messages will be deleted.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"See here for full reference of available event keys: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://logabit.atlassian.net/wiki/spaces/PA/pages/3234168924"}},{"text":" ","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Subscribe to push notifications","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to receive push notifications, you have to subscribe to event keys, called topics, first.","type":"text"}]},{"type":"paragraph","content":[{"text":"This is done in PIPEFORCE by creating a JSON document in a folder with name ","type":"text"},{"text":"push","type":"text","marks":[{"type":"code"}]},{"text":" inside your app. For example ","type":"text"},{"text":"global/app/my.app/push/my-subscription","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]},{"type":"paragraph","content":[{"text":"This JSON document is called ","type":"text"},{"text":"push subscription","type":"text","marks":[{"type":"strong"}]},{"text":" and has a structure like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"enabled\": true,\n \"includeTopics\": [\n \"pipeforce.event.#.error.#\",\n \"pipeforce.event.#.warn.#\",\n \"pipeforce.event.iam.#\"\n ],\n \"excludeTopics\": [\n \"pipeforce.event.iam.refresh.token\",\n \"pipeforce.event.iam.admin.create.realm.role\"\n ],\n \"headers\": {\n \"to\": [\n \"$uri:group:Administrator (Standard)\",\n \"some@mail.tld\",\n \"$uri:wf-task-assignee\"\n ]\n }\n}","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"All push subscriptions inside the ","type":"text"},{"text":"push","type":"text","marks":[{"type":"code"}]},{"text":" folder of any app will be picked-up automatically and activated on save and deactivated on delete. There is no need to extra register it.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The fields of this JSON are described below.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"\"enabled\"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"Is the push subscription enabled (","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":")? Default is ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":" in case attribute is not given.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"\"includeTopics\"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"The routing keys of messages inside the ","type":"text"},{"text":"pipeforce_push","type":"text","marks":[{"type":"code"}]},{"text":" queue to get informed about. ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"\"excludeTopics\"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"The routing keys to exclude explicitly (for example if it is sub-pattern of an includeTopic).","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Both ","type":"text"},{"text":"includeTopics","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"excludeTopics","type":"text","marks":[{"type":"code"}]},{"text":" support the wildcard pattern from RabbitMQ:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"* = A single part between two dots .","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"# = Anything which comes after.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"\"headers\"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"Since a push subscription is based on a mime notification it can contain all of its headers such as:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"to","type":"text","marks":[{"type":"code"}]},{"text":": A list of addresses, to send the push notification to.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"cc","type":"text","marks":[{"type":"code"}]},{"text":": A list of addresses, to send the push notification to in CC.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"bcc","type":"text","marks":[{"type":"code"}]},{"text":": A list of addresses, to send the push notification to in BCC.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"subject","type":"text","marks":[{"type":"code"}]},{"text":": The subject to be used for the push notification. If no subject is set, a default subject is generated.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"es","type":"text","marks":[{"type":"code"}]},{"text":": A list of addresses to exclude from the push notification.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"\"body\"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"The multipart body message to be send as the push notification payload. If no body exists, a default body is generated. Everything described for the body of mime notification can also be applied here.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Topics / Event Keys","type":"text"}]},{"type":"paragraph","content":[{"text":"An ","type":"text"},{"text":"event key","type":"text","marks":[{"type":"strong"}]},{"text":" (also known as ","type":"text"},{"text":"topic)","type":"text","marks":[{"type":"strong"}]},{"text":" is a routing key ","type":"text"},{"text":"pattern","type":"text","marks":[{"type":"strong"}]},{"text":" of an event message which always starts with prefix ","type":"text"},{"text":"pipeforce.event","type":"text","marks":[{"type":"code"}]},{"text":", followed by the concrete event type.","type":"text"}]},{"type":"paragraph","content":[{"text":"It can be used to send ","type":"text"},{"text":"push notifications","type":"text","marks":[{"type":"link","attrs":{"href":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2767224839/Notifications#Push-Notifications"}}]},{"text":" every time such an event happens or to register a ","type":"text"},{"text":"pipeline listener","type":"text","marks":[{"type":"link","attrs":{"href":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2545320123"}}]},{"text":" and listen for such an event to a trigger a pipeline execution. Here is an example how to add such an event message listener to a pipeline:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"pipeline:\n - message.listen:\n key: pipeforce.event.workflow.#\n \n - mail.send:\n to: admin@company.tld\n subject: A workflow event happened.","type":"text"}]},{"type":"paragraph","content":[{"text":"When registering a listener for an event key, also patterns can be used in the event key:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"* ","type":"text","marks":[{"type":"code"}]},{"text":"= Stands for a single word up to the next period ","type":"text"},{"text":".","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"# ","type":"text","marks":[{"type":"code"}]},{"text":"= Stands for multiple words with multiple periods in between.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For example: ","type":"text"},{"text":"pipeforce.event.workflow.#","type":"text","marks":[{"type":"code"}]},{"text":" matches all workflow event messages while ","type":"text"},{"text":"pipeforce.event.workflow.*.my.app","type":"text","marks":[{"type":"code"}]},{"text":" matches only workflow event messages inside the app ","type":"text"},{"text":"my.app","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"See here for full reference of available event keys: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://logabit.atlassian.net/wiki/spaces/PA/pages/3234168924"}},{"text":" ","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Custom Topics","type":"text"}]},{"type":"paragraph","content":[{"text":"You can also send push notifications based on your custom topics. ","type":"text"}]},{"type":"paragraph","content":[{"text":"To do so, you need to configure these steps:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Make sure to send event messages using a routing key format like this ","type":"text"},{"text":"pipeforce.event.","type":"text","marks":[{"type":"code"}]},{"text":" using ","type":"text"},{"text":"message.send","type":"text","marks":[{"type":"code"}]},{"text":" command. Replace ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" by the custom name you would like to use. Best practise is to use the prefix ","type":"text"},{"text":"app","type":"text","marks":[{"type":"code"}]},{"text":" and the name of the app followed by the concrete event name to not potentially collide with other topics from other apps. For example: ","type":"text"},{"text":"pipeforce.event.app.com.company.myapp.myaction","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"This way it is also easy to filter later using patterns. Examples:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pipeforce.event.app.#","type":"text","marks":[{"type":"code"}]},{"text":" = Listens to all events from all apps.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pipeforce.event.app.com.company.#","type":"text","marks":[{"type":"code"}]},{"text":" = Listens to all events from all apps from given ","type":"text"},{"text":"company","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pipeforce.event.app.com.company.myapp.#","type":"text","marks":[{"type":"code"}]},{"text":" = Listens to all events from app ","type":"text"},{"text":"myapp","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pipeforce.event.app.com.company.myapp.myaction","type":"text","marks":[{"type":"code"}]},{"text":" = Listens to the exact ","type":"text"},{"text":"myaction","type":"text","marks":[{"type":"code"}]},{"text":" event.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Create a new push notification configuration inside the ","type":"text"},{"text":"push","type":"text","marks":[{"type":"code"}]},{"text":" folder of your app and make sure to map the ","type":"text"},{"text":"includeTopics","type":"text","marks":[{"type":"code"}]},{"text":" correctly to the recipients. ","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example push notification configuration:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"includeTopics\": [\n \"pipeforce.event.app.com.company.myapp.#\"\n ],\n \"headers\": {\n \"to\": [\n \"$uri:group:my-custom-group\"\n ]\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"This push notification configuration makes sure, every time a custom event for the app ","type":"text"},{"text":"myapp","type":"text","marks":[{"type":"code"}]},{"text":" appears, it will be pushed to all users of group ","type":"text"},{"text":"$uri:group:my-custom-group","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Exclude addresses from topics","type":"text"}]},{"type":"paragraph","content":[{"text":"There is an exclude list to make sure certain push notifications are not sent to these addresses. They can be configured using the header ","type":"text"},{"text":"x-pipeforce-exclude-addresses","type":"text","marks":[{"type":"code"}]},{"text":" as described for the mime notification.","type":"text"}]},{"type":"paragraph","content":[{"text":"Furthermore, it is possible to set the attribute ","type":"text"},{"text":"excludeTopic","type":"text","marks":[{"type":"code"}]},{"text":" for a specific user in IAM. In case the addresses ","type":"text"},{"text":"$uri:group","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"$uri:user","type":"text","marks":[{"type":"code"}]},{"text":" are used and ","type":"text"},{"text":"excludeTopic","type":"text","marks":[{"type":"code"}]},{"text":" exists for a matching user, it will be checked whether this user should be excluded from the push notification.","type":"text"}]},{"type":"paragraph","content":[{"text":"See here as an example:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":784,"alt":"image-20240324-102250.png","id":"64a7d212-6ec5-4cef-be33-4834f7a72c3c","collection":"contentId-2767224839","type":"file","height":420},"marks":[{"type":"border","attrs":{"size":2,"color":"#091e4224"}}]}]},{"type":"paragraph","content":[{"text":"There can be multiple attributes with name ","type":"text"},{"text":"excludeTopics","type":"text","marks":[{"type":"code"}]},{"text":" or the values can be separated by comma. Both approaches work and can also be combined (for example to group certain ","type":"text"},{"text":"excludeTopics","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Templating Push Notifications","type":"text"}]},{"type":"paragraph","content":[{"text":"Since push notifications are based on Mime Notifications, all rules of mime notifications apply.","type":"text"}]},{"type":"paragraph","content":[{"text":"In case no subject or body is defined, a default subject and body is created for each push notification.","type":"text"}]},{"type":"paragraph","content":[{"text":"In case you would like to use a custom text there, you can do so by setting it in the push subscription. For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"includeTopics\": [\n \"pipeforce.event.app.com.company.myapp.#\"\n ],\n \"headers\": {\n \"to\": [\n \"$uri:group:my-custom-group\"\n ],\n \"subject\": \"This is the subject of the push notification\"\n }, \n \"body\": {\n \"contentType\": \"text/plain; charset=UTF-8\",\n \"content\": \"This is the body of the push notification.\"\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"It is also possible to refer to templates in subscription and content (which will be rendered later in the process):","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"includeTopics\": [\n \"pipeforce.event.app.com.company.myapp.#\"\n ],\n \"headers\": {\n \"to\": [\n \"$uri:group:my-custom-group\"\n ],\n \"subject\": \"$uri:property:path/to/my/subject-template\"\n }, \n \"body\": {\n \"contentType\": \"text/plain; charset=UTF-8\",\n \"content\": \"$uri:property:path/to/my/subject-body-template\"\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Inside each template the current ","type":"text"},{"text":"Mime Notification","type":"text","marks":[{"type":"strong"}]},{"text":" (see above) object will be provided which in term contains a field ","type":"text"},{"text":"model","type":"text","marks":[{"type":"code"}]},{"text":" which holds the payload of the current messages. The structure of this payload depends on the event you’re listening to. See: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://logabit.atlassian.net/wiki/spaces/PA/pages/3234168924"}},{"text":" ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Global Push Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"You can disable / enable global push notifications in admin settings. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Note: If disabled, events will ","type":"text"},{"text":"not","type":"text","marks":[{"type":"underline"},{"type":"strong"}]},{"text":" be catched from the ","type":"text"},{"text":"pipeforce_push","type":"text","marks":[{"type":"code"}]},{"text":" queue so outdated, too many event messages there will be deleted.","type":"text"}]},{"type":"paragraph","content":[{"text":"Also see the restrictions of the queue above.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Default Push Subscriptions","type":"text"}]},{"type":"paragraph","content":[{"text":"Inside ","type":"text"},{"text":"global/app/io.pipeforce.admin/push/","type":"text","marks":[{"type":"code"}]},{"text":" there are default push subscriptions for admins, developers and users.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Testing Notifications (dryRun)","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to test notification delivery, you can enable dryRun for such a notification by adding a marker ","type":"text"},{"text":"[pipeforce.dryrun:someName]","type":"text","marks":[{"type":"code"}]},{"text":" in the subject or adding an email address ending in ","type":"text"},{"text":"someName@pipeforce.dryrun","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"In case such a marker exists, the notification wont be delivered but instead stored to the internal cache. From there you can pickup and apply your tests.","type":"text"}]},{"type":"paragraph","content":[{"text":"For further information see an example for dryrun sending emails: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://logabit.atlassian.net/wiki/spaces/PA/pages/2545090700"}},{"text":" .","type":"text"}]}],"version":1}