The Simple Notification System (SNS) is composed of three major parts: topic, application platform, and application endpoint.

• Topic: a logical access point that acts as a communication channel to receive messages. For example, ZWatch can send alarm messages to a topic, and then the topic distributes the messages to the corresponding subscribed endpoints.
• Application platform: the platform through which messages are sent to specific endpoints. For example, an email server is needed if you want to send messages to an email endpoint. The email server mentioned above is an application platform. Currently, two platforms are available: email server and system platform. The system platform is used to send messages to endpoints that do not need a platform, such as DingTalk and HTTP webhook.
• Application endpoint: the endpoint used to receive messages. Currently, the following application endpoints are available: system endpoint, email, DingTalk, HTTP application, and short message service, and Microsoft Service. Before an endpoint can receive messages from a topic, the endpoint must be subscribed to the topic.

Note: Topic has a many-to-many relationship with endpoint. That is, a topic can be subscribed by multiple endpoints, and an endpoint can also subscribe to multiple topics.

When an external system (such as ZWatch) sends a message to a topic, the topic will find all the endpoints that subscribed to the topic, and then send the message through the platform to which the endpoints belong. Assume that you subscribed an email endpoint (an email address) to a topic. When the topic receives an alarm message, it will send an alarm email to the endpoint represented by the email address through the platform (an email server) to which the email endpoint belongs.

Enables or disables a topic. After a topic is disabled, messages sent to the topic are automatically ignored and will not be distributed to the subscribed endpoint.

ChangeSNSTopicState uuid=e034cef9ad3d43e0b3f9c0a316a0f25a stateEvent=disable

Queries a topic. For example,

QuerySNSTopic uuid=b86c9016b4f24953a9edefb53ca0678c

Creates an email platform (email server). For example,

CreateSNSEmailPlatform name=my-sftp-server smtpServer=mail.zstack.org smtpPort=25 username=support@cloud.io password=password

{
    "inventory": {
        "createDate": "Jan 25, 2018 8:43:32 PM",
        "lastOpDate": "Jan 25, 2018 8:43:32 PM",
        "name": "my-sftp-server",
        "smtpPort": 25,
        "smtpServer": "mail.zstack.org",
        "state": "Enabled",
        "type": "Email",
        "username": "support@cloud.io",
        "uuid": "bec03e2d93224c7381782833e8b685ca"
    },
    "success": true
}

Parameters

Name	Description	Optional	Valid Value	Starting Version
smtpServer	The SMTP server address.			2.3
smtpPort	The SMTP port.			2.3
username	The username.			2.3
password	The password.	Yes		2.3
name	The resource name.			2.3
description	The detailed description of the resource.	Yes		2.3
resourceUuid		Yes		2.3
encryptType		Yes	SSL STARTTLS NONE	2.3
userTags	The user tags. For more information, see CreateUserTag.	Yes		2.3
systemTags	The user tags. For more information, see CreateSystemTag.	Yes		2.3
timeout		Yes

Note:

• When you add an email server, the system will automatically detect whether the username, password, email server address, email server port, and encryption type are correct. The waiting time does not exceed 5 seconds.

Tests whether an email platform (email server) is available. For example,

ValidateSNSEmailPlatform uuid=bec03e2d93224c7381782833e8b685ca

Queries an application platform. For example,

QuerySNSApplicationPlatform uuid=b3454k6ll687h23345jh24hk5

Enables or disables an application platform. After the platform is disabled, you can no longer send emails to an endpoint through this platform.

ChangeSNSApplicationPlatformState uuid=bec03e2d93224c7381782833e8b685ca stateEvent=disable

Creates an email endpoint. For example,

CreateSNSEmailEndpoint name=operator email=operator@zstack.org

{
    "inventory": {
        "createDate": "Jan 25, 2018 8:57:14 PM",
        "email": "operator@zstack.org",
        "lastOpDate": "Jan 25, 2018 8:57:14 PM",
        "name": "operator",
        "platformUuid": "bec03e2d93224c7381782833e8b685ca",
        "state": "Enabled",
        "type": "Email",
        "uuid": "b03b125230b0406ea198919954ae3928"
    },
    "success": true
}

Creates an HTTP webhook endpoint. For example,

CreateSNSHttpEndpoint name=http url=http://localhost:8080/webhook-url username=url-username password=url-password

{
    "inventory": {
        "createDate": "Jan 25, 2018 9:01:30 PM",
        "lastOpDate": "Jan 25, 2018 9:01:30 PM",
        "name": "http",
        "platformUuid": "02d24b9b0a7f4ee1846f15cda248ceb7",
        "state": "Enabled",
        "type": "HTTP",
        "url": "http://localhost:8080/webhook-url",
        "username": "url-username",
        "uuid": "d9d8186eeed245e0b18ec8deef185fb7"
    },
    "success": true
}

Creates a DingTalk endpoint, which is a DingTalk robot. For example,

CreateSNSDingTalkEndpoint name=dingding url=https://oapi.dingtalk.com/robot/send?access_token=128f268950234c6c2f065fe88be6cc26d780e9d9863d63eae12be831605345 atPersonPhoneNumbers=+86-12900010002,+86-13977889933

{
    "inventory": {
        "atAll": false,
        "atPersonPhoneNumbers": [
            "+86-12900010002",
            "+86-13977889933"
        ],
        "createDate": "Jan 25, 2018 9:11:00 PM",
        "lastOpDate": "Jan 25, 2018 9:11:00 PM",
        "name": "dingding",
        "platformUuid": "02d24b9b0a7f4ee1846f15cda248ceb7",
        "state": "Enabled",
        "type": "DingTalk",
        "url": "https://oapi.dingtalk.com/robot/send?access_token=128f268950234c6c2f065fe88be6cc26d780e9d9863d63eae12be831605345",
        "uuid": "2663ecb5356a4fbeb6cde202b2e6eaf1"
    },
    "success": true
}

Changes the name of an application endpoint, or modifies the endpoint description. If you want to update specific fields (such as url and email) of the endpoint, the endpoint will be deleted and then rebuilt. For example,

UpdateSNSApplicationEndpoint uuid=2663ecb5356a4fbeb6cde202b2e6eaf1 name=my-endpoint

Queries an application endpoint. For example,

QuerySNSApplicationEndpoint

Subscribes an endpoint to a topic. After subscription, messages sent to the topic will be automatically sent to the endpoint. For example,

SubscribeSNSTopic endpointUuid=b03b125230b0406ea198919954ae3928 topicUuid=e034cef9ad3d43e0b3f9c0a316a0f25a

Queries a topic subscriber. That is, checks which endpoints are subscribed to a topic. For example,

QuerySNSTopicSubscriber topicUuid=71efab26b4f84a62b001ec9b222efe47

Unsubscribes an endpoint from a topic. For example,

UnsubscribeSNSTopic endpointUuid=b03b125230b0406ea198919954ae3928 topicUuid=e034cef9ad3d43e0b3f9c0a316a0f25a

SNS has some built-in system topics. Some predefined messages are sent to the system topics. You can subscribe to these topics to obtain information of interest.

Note:

• System topics cannot be deleted or changed. UUIDs of system topics are predefined constant values.
• System topics can be hard coded.

QuerySNSTopic  name=system-alarm

{
    "inventories": [
        {
            "createDate": "Jan 10, 2018 12:11:09 AM",
            "description": "topic for reporting system defined alarms",
            "lastOpDate": "Jan 10, 2018 12:11:09 AM",
            "name": "system-alarm",
            "state": "Enabled",
            "uuid": "e7d6f5e23bb74e99a2777126078b551c"
        }
    ],
    "success": true
}

Alarms predefined by ZWatch send alarm messages to system alarm topics. You can use a system alarm topic as a custom alarm topic.

Use System HTTP Endpoint to Receive Messages from System Alarm Topics

An internal system (usually the UI) needs a way to receive messages from system alarm topics. You can use a system HTTP endpoint to act as the way mentioned above by configuring the following fields in zstack.properties:

sns.systemTopic.endpoints.http.url = The HTTP URL to receive POST messages.
sns.systemTopic.endpoints.http.url.username = Optional. The username of the HTTP request.
sns.systemTopic.endpoints.http.url.password = Optional. The password of the HTTP request.

If you need to set the username or password, both fields need to be set at the same time. Otherwise, the setting will not take effect. The HTTP endpoint can receive messages no matter the system alarm topic is enabled or disabled.

Note:

You can use the zstack-configure command to configure the fields mentioned above.

QuerySNSTopic  name=system-alarm

{
    "inventories": [
        {
            "createDate": "Jan 10, 2018 12:11:09 AM",
            "description": "the topic to publish API requests and responses",
            "lastOpDate": "Jan 10, 2018 12:11:09 AM",
            "name": "api",
            "state": "Enabled",
            "uuid": "7bfa0eb8555b3528ace936edfd1d74f1"
        }
    ],
    "success": true
}

ZStack will send all API requests and responses to an API topic. You can subscribe to this topic to obtain API call status. The API topic can only be subscribed by HTTP endpoints. The messages received by an HTTP endpoint is the API text in JSON format.

Note:

The API requests received by an API topic are bare requests. If the password field is included in a request (such as the API request for adding a host), this field will also be sent to an endpoint. For security reasons, API topics can only be subscribed by endpoints created by the administrator. The administrator must use API topics only for internal integration or debugging.