README

真正的全渠道组件

该消息服务将自己定位为终极全渠道组件，通过提供独特的多渠道通信能力。此服务不仅限于SMS、电子邮件和政府消息箱，而且还通过支持通过WhatsApp、Facebook和LinkedIn发送消息，拥抱了社交媒体和消息应用的强大功能。这种做法确保政府机构能够触及广泛的受众，无论他们偏好的通信平台是什么。

此外，通过集成Slack等聊天服务，消息服务扩展了其范围，成为内部和外部通信的理想平台。这一补充通过提供一个流畅和高效的通信环境，加强了政府机构与公民、团队和部门之间的桥梁，无论在何处。

此外，它还引入了对推送通知的支持，这些通知可以直接在用户的浏览器或移动设备上交付。这项技术使政府机构能够发送实时更新和重要信息，从而进一步扩大其通信的参与度和覆盖范围。

通过Postex集成发送实体邮件，通过在数字和传统通信方法之间提供无缝过渡，完成了全渠道服务。这种全面的方法确保每个公民都能有效地被触及，无论他们是否偏好数字媒体、传统邮件、社交媒体、聊天服务或直接通知。这样，政府通信的可达性和效率就以一种创新的方式得到了提高，符合数字时代。

广泛的供应商支持

CustomerInteractionBundle的消息服务利用了Symfony Notifier组件，这是一个灵活且强大的系统，旨在使开发人员能够通过多种渠道发送通知。通过这个基础，开发人员可以轻松地与广泛的第三方服务集成，将消息服务变成一个真正的全渠道通信平台。Symfony Notifier不仅支持传统的通信方法，如电子邮件和短信，还支持现代消息应用和社交网络，甚至提供了向浏览器和移动设备发送推送通知的能力。

Symfony Notifier的灵活性在于其设计，这使得开发人员可以轻松添加和配置新的“传输”渠道，以满足应用程序的需求。这使得它成为寻求能够增长并适应其公民不断变化的通信偏好的解决方案的政府机构的一个理想选择。

根据通知自动发送消息

使用Common Gateway管理员用户界面进行安装

一旦正确设置了一个包（如本存储库），Common Gateway可以在没有额外配置的情况下发现该包。转到“插件”标签以搜索、选择和安装插件。

使用PHP命令安装

要执行以下命令，您需要Composer或已经具有PHP和Composer的docker化安装。

在终端和根文件夹中的Composer方法

用于插件安装

$composer require common-gateway/customer-notifications-bundle:dev-main

用于安装模式

$php bin/console commongateway:install common-gateway/customer-notifications-bundle

终端和根目录中的docker化方法

用于插件安装

$docker-compose exec php composer require common-gateway/customer-notifications-bundle:dev-main

用于安装模式

$docker-compose exec php bin/console commongateway:install common-gateway/customer-notifications-bundle

邮件和/或短信配置

此包可用于（仅）通过创建特定的电子邮件或短信Common Gateway操作来发送电子邮件或短信消息。为此，您需要为EmailHandler或SmsHandler分别创建一个Common Gateway操作。操作处理程序。

如何创建电子邮件或短信操作

这些操作的配置大部分可以通过使用网关管理UI进行配置，除了一个配置属性：variables。如果您想/需要使用或更改此操作配置属性：variables，我们建议直接将您的操作包含在您正在使用的包的安装文件中（Common Gateway插件）或使用API平台工具如Postman直接POST（、PATCH或UPDATE）您的操作到您正在工作的Common Gateway。

因此，现在您已经知道了如何创建电子邮件和/或短信操作，您也应该了解和了解这些操作配置的要求

name，您的操作需要一个名称。
reference，每个操作都需要一个唯一的参考URL，以https://{your-domain}/action/{short-name-for-your-bundle}开始，以.action.json结束，例如："https://commongateway.nl/action/notifications.ZaakCreatedEmailAction.action.json"
每个操作需要监听一个或多个Common Gateway事件，您可以将这些事件添加到操作的listens数组中。
一些将比较到操作数据的JsonLogic conditions，这些条件决定了操作何时触发。使用{"==": [1, 1]}表示'始终为真'。
class，对于此类型的操作，应该是"CommonGateway\CustomerNotificationsBundle\ActionHandler\EmailHandler"或"CommonGateway\CustomerNotificationsBundle\ActionHandler\SmsHandler"。
包含您电子邮件或短信操作特定配置的configuration数组，这可能是此列表中最复杂的事情，因此，在以下摘要/列表之后，您将找到更详细的说明。

电子邮件和短信操作配置

电子邮件和短信操作配置非常相似，以下是可以用于电子邮件和短信操作的配置属性列表

[必需] serviceDNS 邮件或短信提供者的DNS。邮件或短信。
[必需] template 您的电子邮件或短信模板。这应该是一个base64编码的twig模板。有关（未base64编码的）示例，请参阅根/src/EmailTemplates文件夹。
【必填】 sender 发送者。用于电子邮件操作的邮箱。用于短信的 'from' 字符串（例如：Gemeente%20Mordor）。在此可以使用twig来添加一个或多个来自 variables 数组的变量。
【必填】 receiver 接收者。用于电子邮件操作的邮箱。用于短信的电话号码。在此可以使用twig来添加来自 variables 数组的变量。
variables 变量数组，使用此数组可以配置哪些变量（variables 数组的键）可以在模板中使用，并通过使用点符号引用Action数据中的属性来填充这些值（variables 数组的值）。

【注意】有关SMS操作的示例，请参阅根目录下 Installation/Action 文件夹中所有使用ActionHandler（类）CommonGateway\CustomerNotificationsBundle\ActionHandler\SMSHandler 的操作。

【注意】只要使用的变量在 variables 数组中定义得较早或较高，就可以使用twig在 variables 数组中的另一个值中添加变量，例如变量.body中的此示例。

电子邮件操作特定配置

与短信操作配置相比，电子邮件操作配置有一些额外的属性可供使用。对于所有这些属性，都可以使用twig来添加一个或多个来自 variables 数组的变量。

【必填】 subject 电子邮件的主题。
cc 抄送，应接收此邮件副本的邮箱。
bcc 隐私抄送，应接收副本但其他接收者不知道的人。
replyTo 接收者应回复的地址，只有当它与发送者地址不同时才提供。
priority 电子邮件的优先级，可选。

【注意】有关电子邮件操作的示例，请参阅根目录下 Installation/Action 文件夹中所有使用ActionHandler（类）CommonGateway\CustomerNotificationsBundle\ActionHandler\EmailHandler 的操作。

通知配置

还可以通过通知触发您配置的电子邮件和/或短信操作。CustomerNotificiationsBundle添加了一个新的Common Gateway端点，可以用于将您的ZGW通知发送到：{{gateway-domain}}/api/notifications

发送到此端点的所有通知将触发一个Common Gateway事件
notifications.notification.created

通过创建使用NotificationsHandler ActionHandler 的Common Gateway操作，您可以配置哪些通知应触发发送电子邮件或短信的新Common Gateway事件。

如何创建通知操作

通常您可以通过网关管理UI创建操作，但通知操作有一些复杂的配置，目前无法通过网关UI进行配置。因此，建议将您的操作直接包含在您正在处理的包（Common Gateway插件）的安装文件中，或者使用postman等API平台工具直接POST（、PATCH或UPDATE）您在Common Gateway上的操作。

现在您知道了如何创建通知操作，您还应该了解（通知）操作的配置要求。

name，您的操作需要一个名称。
每个操作需要一个唯一的引用，引用URL以https://{你的域名}/action/开头，以.action.json结尾，例如："https://commongateway.nl/action/notifications.ZaakCreatedAction.action.json"。
每个操作需要监听一个或多个通用网关事件，您可以将这些事件添加到操作中的listens数组中。如果您正在使用ZGW通知，这可能是["notifications.notification.created"]。
一些JsonLogic的条件，这些条件决定了您的通知操作何时被触发。当它被触发时，它将抛出触发发送电子邮件或短信操作的事件。下面将提供示例。
类，您的通知操作应该是"CommonGateway\CustomerNotificationsBundle\ActionHandler\NotificationsHandler"。
一个包含获取和传递信息到您的电子邮件和/或短信操作的特定配置的配置数组，这是此列表中最复杂的事情，因此下面将提供更详细说明和示例。

通知操作条件

要只为特定类型的通知发送电子邮件或短信，您可以使用操作条件与操作配置相结合，只使您的操作触发您想要的通知。操作条件使用JsonLogic来比较操作数据与您的条件。

以下是一个“案件创建”/“zaak aangemaakt”通知操作条件的示例

{
    "and": [
        {
            "in": [
                "https://open-zaak.test.buren.opengem.nl/zaken/api/v1",
                {
                    "var": "body.kanaal"
                }
            ]
        },
        {
            "==": [
                {
                    "var": "body.kanaal"
                },
                "zaken"
            ]
        },
        {
            "==": [
                {
                    "var": "body.resource"
                },
                "zaak"
            ]
        },
        {
            "==": [
                {
                    "var": "body.actie"
                },
                "create"
            ]
        }
    ]
}

注意：在这些操作条件中，您可以使用通过操作数据访问的请求的大部分属性，因此除了检查body.bodyProperty外，您还可以检查method=POST。

注意：有关更多示例，请查看根/Installation/Action文件夹中的所有使用操作处理器（类）CommonGateway\CustomerNotificationsBundle\ActionHandler\NotificationsHandler的操作。

在某些情况下，您可能需要检查比仅使用操作条件更多的内容。例如，从ZGW通知hoofdObject或resourceUrl对象中获取和检查信息。有关更多信息，请检查下面的操作配置extraConditions。

通知操作配置

您可以通过几种方式配置通知操作配置，我们将在此处详细介绍您可以配置的内容。（这些信息也应包含在src/ActionHandler/NotificationsHandler.php文件本身中）。大多数属性不是必须添加的，请考虑您用例所需的内容，并添加所需的配置。如果您缺少任何必填字段，您将在测试期间在网关UI中找到有关此的错误日志。

以下是一个“案件状态为完成”/“zaak status is eindstatus”通知的操作配置的非常复杂和详尽的示例。

{
    "extraConditions": {
        "getObjectDataConfig": {
            "source": "https://buren.nl/source/buren.zrc.source.json",
            "notificationProperty": "body.resourceUrl",
            "sourceProperties": ["statustype"],
            "getObjectDataConfig": {
                "forParentProperties": ["statustype"],
                "source": "https://buren.nl/source/buren.ztc.source.json",
                "sourceProperties": ["isEindstatus"]
            }
        },
        "conditions": {
            "isEindstatus": true
        }
    },
    "hoofdObjectSource": "https://buren.nl/source/buren.zrc.source.json",
    "emailConfig": {
        "getObjectDataConfig": {
            "source": "https://buren.nl/source/buren.zrc.source.json",
            "sourceEndpoint": "/rollen",
            "sourceQuery": {
                "zaak": "{{body.hoofdObject}}",
                "omschrijvingGeneriek": "initiator"
            },
            "sourceProperties": ["results.0.betrokkeneIdentificatie.inpBsn"],
            "searchSchemas": ["https://commongateway.nl/klant.partij.schema.json"],
            "searchQuery": {
                "externeIdentificaties.partijIdentificator.objectId": "{{results.0.betrokkeneIdentificatie.inpBsn}}",
                "externeIdentificaties.partijIdentificator.objecttype": "ingeschrevenpersonen"
            }
        },
        "objectConditions": {
            "embedded.voorkeurskanaal.soortDigitaalAdres": "emailadres"
        },
        "throw": "notifications.zaak.status.finished.email"
    },
    "smsConfig": {
        "getObjectDataConfig": "sameAsEmail",
        "objectConditions": {
            "embedded.voorkeurskanaal.soortDigitaalAdres": "telefoonnummer"
        },
        "throw": "notifications.zaak.status.finished.sms"
    },
    "createObjectConfig": {
        "schema": "https://commongateway.nl/klant.klantcontact.schema.json",
        "mapping": "Mapping ref or uuid"
    }
}

注意：有关更多示例，请查看根/Installation/Action文件夹中的所有使用操作处理器（类）CommonGateway\CustomerNotificationsBundle\ActionHandler\NotificationsHandler的操作。

extraConditions

此操作的额外条件使您能够检查来自网关外源对象的属性，并将这些数据用作运行此操作的额外条件。将检查“conditions”数组中的所有条件。

只能使用在sourceProperties数组中定义的属性/键来检查“conditions”数组中的条件。参见上面的示例，我们检查isEindstatus = true，isEindstatus存在于sourceProperties数组中。

使用 getObjectDataConfig 可以配置如何调用源，以获取您为 "条件" 需要的 sourceProperties。 getObjectDataConfig 可以递归使用，如果这样做，您需要添加包含您希望用于调用另一个源 sourceProperties 的数组属性 forParentProperties。请参阅上面的示例此处，"statustype" 是源上包含 URL 的属性，它在第一个 sourceProperties 数组中存在，并在之后的 forParentProperties 中。

getObjectDataConfig 必须始终具有以下属性

source 调用的源引用。
sourceProperties 从源响应中使用的属性。
& 以下之一
- notificationProperty 从通知获取用于在源上调用的 URL。
- sourceEndpoint 定义要调用的特定端点。
- forParentProperties 如果是递归，请在此处添加具有 URL 的源属性名称，以便可以用于调用另一个（或相同的）源。

但 getObjectDataConfig 还可以具有属性

sourceQuery 用于调用源的查询。

hoofdObjectSource

当此属性设置时，通知 hoofdObject 的数据将可在您的电子邮件和 SMS 模板中使用。将使用通知 hoofdObject URL 调用指定的源（引用），并返回值将通过抛出的电子邮件/SMS 事件传递。
仅当需要时才设置此属性。

resourceUrlSource

与 hoofdObjectSource 完全相同，但针对通知 resourceUrl。 (如上例所示中未显示)
仅当需要时才设置此属性。

emailConfig

这包含在接收到通知后发送电子邮件的配置。如果不存在，则无法发送电子邮件。

getObjectDataConfig 可以用于配置如何查找和将一个 Common Gateway 对象的数据添加到电子邮件动作数据（以及通过电子邮件模板的电子邮件消息）。
objectConditions 可以用于添加一些最终条件，使用通过 getObjectDataConfig 找到的对象进行检查。如果这些条件失败，则不会发送电子邮件。（只要 objectConditions 为空，如果没有通过 getObjectDataConfig 找到对象，则也不会发送电子邮件）。
throw 是我们应抛出的事件，以触发另一个 EmailHandler 动作，该动作将发送实际的电子邮件。

有关 getObjectDataConfig 的工作原理的基本信息可以在 extraConditions 属性的说明中找到，请先查看该说明。了解 & emailConfig 特定属性

source 调用的源引用。
sourceProperties 这是从源响应中获取属性名称的数组。
searchSchemas 要在网关中搜索对象时使用的 Schema 引用数组。
searchQuery 要在网关中搜索对象时使用的查询数组，在此处使用 {{sourcePropertyName}} 以插入使用 sourceProperties 获取的值。请参阅上面的示例此处。

注意：也可以递归地使用 getObjectDataConfig，请参阅 extraConditions 了解如何执行此操作。

smsConfig

这包含在接收到通知后发送 SMS 的配置。如果不存在，则无法发送 SMS。

getObjectDataConfig 可用于配置如何查找和添加一个通用网关对象的数据到 SMS 动作数据（以及通过 SMS 模板发送的 SMS 消息），如果设置为 "sameAsEmail"，则与电子邮件相同的对象（来源的响应）将被使用（或相同的配置）。
objectConditions 可用于添加一些最终条件，以使用 getObjectDataConfig 找到的对象进行验证。如果这些条件失败，则不会发送 SMS。（只要 objectConditions 不为空，如果使用 getObjectDataConfig 没有找到对象，则也不会发送 SMS）。
throw 是我们应该抛出的一个事件，以触发另一个将发送实际 SMS 的 SMSHandler 动作。

有关 getObjectDataConfig 的工作方式的更多详细信息，请参阅 emailConfig 属性。

注意：smsConfig 的工作方式与 emailConfig 完全相同，只是使用 "sameAsEmail" 不同。

createObjectConfig

目前这个功能没有任何作用，这是一个正在进行中的工作。
当这个功能完成时，它可以用在处理通知的末尾创建特定的通用网关对象。例如，在发送电子邮件和/或 SMS 之后创建一个 'klantcontact' 对象。

common-gateway / customer-notifications-bundle

维护者

详细信息