diff --git a/api-specs/api/resources/subscriptions.raml b/api-specs/api/resources/subscriptions.raml index e760e63784..454334a4fb 100644 --- a/api-specs/api/resources/subscriptions.raml +++ b/api-specs/api/resources/subscriptions.raml @@ -34,7 +34,7 @@ post: is: - deprecatable201 description: | - A test message is sent to ensure the correct configuration of the Destination. If the message cannot be delivered, the Subscription will not be created. The payload of the test message is a notification of type [ResourceCreated](/../api/projects/subscriptions#resourcecreateddeliverypayload) for the `resourceTypeId` `subscription`. + A test notification is sent to ensure the correct configuration of the Destination. If the notification cannot be delivered, the Subscription will not be created. The payload of the test notification is of type [ResourceCreated](/../api/projects/subscriptions#resourcecreateddeliverypayload) for the `resourceTypeId` `subscription`. body: application/json: type: SubscriptionDraft diff --git a/api-specs/api/types/extension/ExtensionResourceTypeId.raml b/api-specs/api/types/extension/ExtensionResourceTypeId.raml index 359f8f5c29..4f019eca2b 100644 --- a/api-specs/api/types/extension/ExtensionResourceTypeId.raml +++ b/api-specs/api/types/extension/ExtensionResourceTypeId.raml @@ -13,6 +13,7 @@ enum: - staged-quote - quote - business-unit + - shopping-list (enumDescriptions): cart: Extension triggered for operations on [Carts](/../api/projects/carts). order: Extension triggered for operations on [Orders](/../api/projects/orders). @@ -22,3 +23,4 @@ enum: staged-quote: Extension triggered for operations on [StagedQuotes](/../api/projects/staged-quotes). quote: Extension triggered for operations on [Quotes](/../api/projects/quotes). business-unit: Extension triggered for operations on [BusinessUnits](/../api/projects/business-units). + shopping-list: Extension triggered for operations on [ShoppingLists](/../api/projects/shoppingLists). diff --git a/api-specs/api/types/subscription/AwsAuthenticationMode.raml b/api-specs/api/types/subscription/AwsAuthenticationMode.raml index c306384a33..b2c0a78117 100644 --- a/api-specs/api/types/subscription/AwsAuthenticationMode.raml +++ b/api-specs/api/types/subscription/AwsAuthenticationMode.raml @@ -10,5 +10,5 @@ enum: Credentials: | Subscriptions with `Credentials` authentication mode are authenticated using an `accessKey` and `accessSecret` pair. This is the default authentication mode for backwards compatibility. IAM: | - Subscriptions with `IAM` authentication mode are authenticated using Identity and Access Management (IAM). For this authentication mode, the following user requires permissions to send messages to the queue or publish to the topic: `arn:aws-cn:iam::417094354346:user/subscriptions` if the Project is hosted in the China (AWS, Ningxia) Region; `arn:aws:iam::362576667341:user/subscriptions` for all other [Regions](/../api/general-concepts#regions). This is the recommended authentication mode, as it doesn't require additional key management. + Subscriptions with `IAM` authentication mode are authenticated using Identity and Access Management (IAM). For this authentication mode, the following user requires permissions to send notifications to the queue or publish to the topic: `arn:aws-cn:iam::417094354346:user/subscriptions` if the Project is hosted in the China (AWS, Ningxia) Region; `arn:aws:iam::362576667341:user/subscriptions` for all other [Regions](/../api/general-concepts#regions). This is the recommended authentication mode, as it doesn't require additional key management. default: Credentials diff --git a/api-specs/api/types/subscription/AzureEventGridDestination.raml b/api-specs/api/types/subscription/AzureEventGridDestination.raml index e00663a105..ef7e5abe73 100644 --- a/api-specs/api/types/subscription/AzureEventGridDestination.raml +++ b/api-specs/api/types/subscription/AzureEventGridDestination.raml @@ -5,8 +5,8 @@ displayName: AzureEventGridDestination discriminatorValue: EventGrid example: !include ../../examples/Subscription/SubscriptionAzureEventGridDestination.json description: | - [Azure Event Grid](https://azure.microsoft.com/en-us/products/event-grid/) can be used to push messages to Azure Functions, HTTP endpoints (webhooks), and several other Azure tools. Event Grid can only be used with the [CloudEventsFormat](ctp:api:type:CloudEventsFormat). - To set up a Subscription with Azure Event Grid, first create a topic in the [Azure Portal](https://azure.microsoft.com/en-us/get-started/azure-portal/). To allow Composable Commerce to push messages to your topic, provide an [access key](https://docs.microsoft.com/en-us/azure/event-grid/get-access-keys). + [Azure Event Grid](https://azure.microsoft.com/en-us/products/event-grid/) can be used to push notifications to Azure Functions, HTTP endpoints (webhooks), and several other Azure tools. Event Grid can only be used with the [CloudEventsFormat](ctp:api:type:CloudEventsFormat). + To set up a Subscription with Azure Event Grid, first create a topic in the [Azure Portal](https://azure.microsoft.com/en-us/get-started/azure-portal/). To allow Composable Commerce to push notifications to your topic, provide an [access key](https://docs.microsoft.com/en-us/azure/event-grid/get-access-keys). properties: uri: type: string diff --git a/api-specs/api/types/subscription/AzureServiceBusDestination.raml b/api-specs/api/types/subscription/AzureServiceBusDestination.raml index 6f7e400aa8..29e47761f0 100644 --- a/api-specs/api/types/subscription/AzureServiceBusDestination.raml +++ b/api-specs/api/types/subscription/AzureServiceBusDestination.raml @@ -5,7 +5,7 @@ displayName: AzureServiceBusDestination discriminatorValue: AzureServiceBus example: !include ../../examples/Subscription/SubscriptionAzureServiceBusDestination.json description: | - [Azure Service Bus](https://azure.microsoft.com/en-us/products/service-bus/) can be used as a pull-queue with [Queues](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#queues), or to fan-out messages with [Topics and Subscriptions](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions). + [Azure Service Bus](https://azure.microsoft.com/en-us/products/service-bus/) can be used as a pull-queue with [Queues](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#queues), or to fan-out notifications with [Topics and Subscriptions](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions). To set up a Subscription with Azure Service Bus, first create a queue/topic in the [Azure Portal](https://azure.microsoft.com/en-us/get-started/azure-portal/) with a Shared Access Policy including the `Send` permission. properties: connectionString: diff --git a/api-specs/api/types/subscription/CloudEventsPayload.raml b/api-specs/api/types/subscription/CloudEventsPayload.raml index b0b6a601bb..b71e655504 100644 --- a/api-specs/api/types/subscription/CloudEventsPayload.raml +++ b/api-specs/api/types/subscription/CloudEventsPayload.raml @@ -5,7 +5,7 @@ displayName: CloudEventsPayload discriminatorValue: CloudEvents example: !include ../../examples/Subscription/cloudevents-payload.example.json description: | - The [CloudEventsFormat](ctp:api:type:CloudEventsFormat) represents event data in a way that conforms to a common specification. The message payload can be found inside the `data` field. + The [CloudEventsFormat](ctp:api:type:CloudEventsFormat) represents event data in a way that conforms to a common specification. The payload can be found inside the `data` field. properties: specversion: type: string diff --git a/api-specs/api/types/subscription/ConfluentCloudDestination.raml b/api-specs/api/types/subscription/ConfluentCloudDestination.raml index 4173f99b04..1b9b0c098e 100644 --- a/api-specs/api/types/subscription/ConfluentCloudDestination.raml +++ b/api-specs/api/types/subscription/ConfluentCloudDestination.raml @@ -5,9 +5,9 @@ displayName: ConfluentCloudDestination discriminatorValue: ConfluentCloud example: !include ../../examples/Subscription/SubscriptionConfluentCloudDestination.json description: | - This destination can be used to push events and messages to [Confluent Cloud](https://www.confluent.io/confluent-cloud/). + This destination can be used to push notifications to [Confluent Cloud](https://www.confluent.io/confluent-cloud/). To set up a Subscription of this type, first, create a topic in Confluent Cloud. - Then, to allow Composable Commerce to push events and messages to your topic, generate [API keys](https://docs.confluent.io/cloud/current/access-management/authenticate/api-keys/api-keys.html) for your topic, and create the Subscription destination using the generated credentials. + Then, to allow Composable Commerce to push notifications to your topic, generate [API keys](https://docs.confluent.io/cloud/current/access-management/authenticate/api-keys/api-keys.html) for your topic, and create the Subscription destination using the generated credentials. The Composable Commerce producer uses the following values: `SASL_SSL` for`security.protocol`, `PLAIN` for`sasl.mechanism`, and the default value (1048576) for `max.request.size`. properties: diff --git a/api-specs/api/types/subscription/DeliveryPayload.raml b/api-specs/api/types/subscription/DeliveryPayload.raml index 28eeca823f..fd04639927 100644 --- a/api-specs/api/types/subscription/DeliveryPayload.raml +++ b/api-specs/api/types/subscription/DeliveryPayload.raml @@ -10,7 +10,7 @@ properties: type: string description: | `key` of the [Project](ctp:api:type:Project). - Useful in message processing if the Destination receives events from multiple Projects. + Useful for processing notifications if the Destination receives them from multiple Projects. notificationType: type: string description: | @@ -18,7 +18,7 @@ properties: resource: type: Reference description: | - Reference to the resource that triggered the message. + Reference to the resource that triggered the notification. resourceUserProvidedIdentifiers?: type: UserProvidedIdentifiers description: | diff --git a/api-specs/api/types/subscription/GoogleCloudPubSubDestination.raml b/api-specs/api/types/subscription/GoogleCloudPubSubDestination.raml index 07cbecaa70..679f01d18e 100644 --- a/api-specs/api/types/subscription/GoogleCloudPubSubDestination.raml +++ b/api-specs/api/types/subscription/GoogleCloudPubSubDestination.raml @@ -8,7 +8,7 @@ description: | Destination for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/) that can be used for [Pull subscriptions](https://cloud.google.com/pubsub/docs/pull) as well as for [Push subscriptions](https://cloud.google.com/pubsub/docs/push). The `topic` must give the `pubsub.topics.publish` permission to the service account `subscriptions@commercetools-platform.iam.gserviceaccount.com`. - If used with the [CloudEventsFormat](#cloudeventsformat), the message conforms to the [PubSub Protocol Binding](https://github.com/google/knative-gcp/blob/master/docs/spec/pubsub-protocol-binding.md) of the [Structured Content Mode](https://github.com/google/knative-gcp/blob/master/docs/spec/pubsub-protocol-binding.md#32-structured-content-mode). + If used with the [CloudEventsFormat](#cloudeventsformat), the notification conforms to the [PubSub Protocol Binding](https://github.com/google/knative-gcp/blob/master/docs/spec/pubsub-protocol-binding.md) of the [Structured Content Mode](https://github.com/google/knative-gcp/blob/master/docs/spec/pubsub-protocol-binding.md#32-structured-content-mode). properties: projectId: type: string diff --git a/api-specs/api/types/subscription/MessageDeliveryPayload.raml b/api-specs/api/types/subscription/MessageDeliveryPayload.raml index 48c27b12d7..547b095512 100644 --- a/api-specs/api/types/subscription/MessageDeliveryPayload.raml +++ b/api-specs/api/types/subscription/MessageDeliveryPayload.raml @@ -34,7 +34,7 @@ properties: type: number format: int64 description: | - Version of the resource on which the change was performed. + Version of the resource on which the update was performed. payloadNotIncluded?: type: PayloadNotIncluded description: | diff --git a/api-specs/api/types/subscription/SnsDestination.raml b/api-specs/api/types/subscription/SnsDestination.raml index ccffd8317c..38ab0e5fb9 100644 --- a/api-specs/api/types/subscription/SnsDestination.raml +++ b/api-specs/api/types/subscription/SnsDestination.raml @@ -7,7 +7,7 @@ example: !include ../../examples/Subscription/SubscriptionSnsDestination.json description: | [AWS SNS](https://aws.amazon.com/sns/) can be used to push messages to AWS Lambda, HTTP endpoints (webhooks), or fan-out messages to SQS queues. The SQS queue must be a [Standard](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/standard-queues.html) queue type. - We recommend setting `authenticationMode` to `IAM`, to avoid unnecessary key management. For IAM authentication and before creating the Subscription, give permissions to the following user account: `arn:aws-cn:iam::417094354346:user/subscriptions` if the Project is hosted in the China (AWS, Ningxia) Region; `arn:aws:iam::362576667341:user/subscriptions` for all other [Regions](/../api/general-concepts#regions). Otherwise, a test message will not be sent. + We recommend setting `authenticationMode` to `IAM`, to avoid unnecessary key management. For IAM authentication and before creating the Subscription, give permissions to the following user account: `arn:aws-cn:iam::417094354346:user/subscriptions` if the Project is hosted in the China (AWS, Ningxia) Region; `arn:aws:iam::362576667341:user/subscriptions` for all other [Regions](/../api/general-concepts#regions). Otherwise, a test notification will not be sent. If you prefer to use `Credentials` for authentication, we recommend [creating an IAM user](https://docs.aws.amazon.com/sns/latest/dg/sns-setting-up.html#create-iam-user) with an `accessKey` and `accessSecret` pair specifically for each Subscription. diff --git a/api-specs/api/types/subscription/Subscription.raml b/api-specs/api/types/subscription/Subscription.raml index 4874763e9d..00a2e2a902 100644 --- a/api-specs/api/types/subscription/Subscription.raml +++ b/api-specs/api/types/subscription/Subscription.raml @@ -36,11 +36,11 @@ properties: changes: type: ChangeSubscription[] description: | - Change notifications subscribed to. + Changes subscribed to. destination: type: Destination description: | - Messaging service to which the messages are to be sent. + Messaging service to which the notifications are sent. key?: type: string description: | diff --git a/api-specs/api/types/subscription/SubscriptionDraft.raml b/api-specs/api/types/subscription/SubscriptionDraft.raml index 6e71106941..1e519813c4 100644 --- a/api-specs/api/types/subscription/SubscriptionDraft.raml +++ b/api-specs/api/types/subscription/SubscriptionDraft.raml @@ -9,11 +9,11 @@ properties: changes?: type: ChangeSubscription[] description: | - Change notifications to be subscribed to. + Changes to be subscribed to. destination: type: Destination description: | - Messaging service to which the messages are sent. + Messaging service to which the notifications are sent. key?: type: string description: | diff --git a/api-specs/api/types/subscription/SubscriptionHealthStatus.raml b/api-specs/api/types/subscription/SubscriptionHealthStatus.raml index eb2ca0462c..7687c9887e 100644 --- a/api-specs/api/types/subscription/SubscriptionHealthStatus.raml +++ b/api-specs/api/types/subscription/SubscriptionHealthStatus.raml @@ -2,14 +2,14 @@ (package): Subscription displayName: SubscriptionHealthStatus description: | - The health status of the Subscription that indicates whether messages are being delivered. + The health status of the Subscription that indicates whether notifications are being delivered. type: string (enumDescriptions): - Healthy: Delivers messages as expected. - ConfigurationError: Messages cannot be delivered with the current configuration. Common causes are deleting the Destination queue, deleting access credentials, or removing the necessary permissions. The configuration can be fixed by re-creating the configuration on the Destination side, or by setting a new configuration with the [Change Destination](/../api/projects/subscriptions#change-destination) update action. If the configuration is fixed, undelivered messages will be delivered and the `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus). `ConfigurationError` is automatically turned into `ConfigurationErrorDeliveryStopped` after some time. For more information, see [Delivery Guarantees](#delivery-guarantees). - ConfigurationErrorDeliveryStopped: Does not deliver messages with the current configuration and the delivery of the messages is no longer attempted. If the configuration is fixed, undelivered messages are not retained and will not be delivered. The `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus) as soon as new messages can be delivered. - TemporaryError: Does not deliver messages temporarily due to reasons other than a configuration error. For example, the Destination has a temporary outage. - ManuallySuspended: Does not deliver messages with the current configuration and the delivery of the messages is no longer attempted. Undelivered messages are not retained and will not be delivered. The `status` will not automatically change to [Healthy](ctp:api:type:SubscriptionHealthStatus). To return your subscriptions to a [Healthy](ctp:api:type:SubscriptionHealthStatus) status, contact the [Composable Commerce support team](https://support.commercetools.com/). + Healthy: Delivers notifications as expected. + ConfigurationError: Notifications cannot be delivered with the current configuration. Common causes are deleting the Destination queue, deleting access credentials, or removing necessary permissions. You can fix the configuration by re-creating the configuration on the Destination side, or by setting a new configuration with the [Change Destination](/../api/projects/subscriptions#change-destination) update action. After the configuration is fixed, undelivered notifications will be delivered and the `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus). `ConfigurationError` is automatically turned into `ConfigurationErrorDeliveryStopped` after some time. For more information, see [Delivery Guarantees](#delivery-guarantees). + ConfigurationErrorDeliveryStopped: Does not deliver notifications with the current configuration and the delivery of the notifications is no longer attempted. After the configuration is fixed, undelivered notifications are not retained and will not be delivered. The `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus) as soon as new notifications can be delivered. + TemporaryError: Does not deliver notifications temporarily due to reasons other than a configuration error. For example, the Destination has a temporary outage. + ManuallySuspended: Does not deliver notifications with the current configuration and the delivery of the notifications is no longer attempted. Undelivered notifications are not retained and will not be delivered. The `status` will not automatically change to [Healthy](ctp:api:type:SubscriptionHealthStatus). To return your subscriptions to a [Healthy](ctp:api:type:SubscriptionHealthStatus) status, contact the [Composable Commerce support team](https://support.commercetools.com/). enum: - Healthy diff --git a/api-specs/api/types/subscription/updates/SubscriptionChangeDestinationAction.raml b/api-specs/api/types/subscription/updates/SubscriptionChangeDestinationAction.raml index 106ef987ed..9298c2521b 100644 --- a/api-specs/api/types/subscription/updates/SubscriptionChangeDestinationAction.raml +++ b/api-specs/api/types/subscription/updates/SubscriptionChangeDestinationAction.raml @@ -5,7 +5,7 @@ displayName: SubscriptionChangeDestinationAction discriminatorValue: changeDestination example: !include ../../../examples/Subscription/SubscriptionChangeDestinationAction.json description: | - A test message is sent to ensure the correct configuration of the Destination. If the message cannot be delivered, the update will fail. The payload of the test message is a notification of type [ResourceCreated](ctp:api:type:ResourceCreatedDeliveryPayload) for the `resourceTypeId` `subscription`. The `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus), if it isn't already. + A test notification is sent to ensure the correct configuration of the Destination. If the notification cannot be delivered, the update will fail. The payload of the test notification is of type [ResourceCreated](ctp:api:type:ResourceCreatedDeliveryPayload) for the `resourceTypeId` `subscription`. The `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus), if it isn't already. properties: destination: type: Destination