From 1a77aaaa1ada0121f3c4419ae30a3a6fdde3e40c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20D=C3=B6ll?= Date: Fri, 26 Apr 2024 20:22:55 +0200 Subject: [PATCH] Adding extension BAM MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Sebastian Döll --- cloudevents/extensions/README.md | 1 + cloudevents/extensions/bam.md | 129 ++++++++++++++++++ cloudevents/languages/he/extensions/bam.md | 2 + cloudevents/languages/zh-CN/extensions/bam.md | 6 + 4 files changed, 138 insertions(+) create mode 100644 cloudevents/extensions/bam.md create mode 100644 cloudevents/languages/he/extensions/bam.md create mode 100644 cloudevents/languages/zh-CN/extensions/bam.md diff --git a/cloudevents/extensions/README.md b/cloudevents/extensions/README.md index 688c2555..aca707fd 100644 --- a/cloudevents/extensions/README.md +++ b/cloudevents/extensions/README.md @@ -41,6 +41,7 @@ for more information. ## Known Extensions - [Auth Context](authcontext.md) +- [BAM](bam.md) - [Dataref (Claim Check Pattern)](dataref.md) - [Distributed Tracing](distributed-tracing.md) - [Expiry Time](expirytime.md) diff --git a/cloudevents/extensions/bam.md b/cloudevents/extensions/bam.md new file mode 100644 index 00000000..1cdab33c --- /dev/null +++ b/cloudevents/extensions/bam.md @@ -0,0 +1,129 @@ +# Business Activity Monitoring (BAM) Extension + +Business Activity Monitoring (BAM) was originally coined by analysts at +Gartner, and refers to the aggregation, analysis, and presentation of +real-time information about activities inside organizations, customers, +and partners. + +The activity monitoring consists of a model of a business process, +which can consists of multiple transactions (e.g. order, payment, invoice), +and these transactions can have multiple steps. The technical processing +represented by a transaction instance `bamtxid` is then correlated with +the steps in those transactions of the business process. + +This extension defines attributes that can be included within a CloudEvent +to describe the business activity that the event is associated with. + +Producers and consumers are free to define an out-of-band agreement on the +semantic meaning, or valid values, for the attribute. + +## Notational Conventions + +As with the main [CloudEvents specification](../spec.md), the key words "MUST", +"MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", +"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as +described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +However, the scope of these key words is limited to when this extension is +used. For example, an attribute being marked as "REQUIRED" does not mean +it needs to be in all CloudEvents, rather it needs to be included only when +this extension is being used. + +## Attributes + +### bamtxid + +- Type: `String` +- Description: A unique identifer for the instance of a transaction. + This identifier connects the actual processing in the distributed + system (e.g. payment, invoice, warehouse) with the model of this process. +- Constraints + - REQUIRED + - MUST be a non-empty string + - RECOMMENDED as monotonically increasing and contiguous identifier + that is lexicographically-sortable. + +### bampid + +- Type: `String` +- Description: A unique identifier for the model of the business process + that is associated with instance of the transaction `bamtxid`. + A business process is a collection of transactions. These transactions + can run in sequence or parallel (e.g. payment, invoice, warehouse). +- Constraints + - REQUIRED + - MUST be a non-empty string + - RECOMMENDED a alphanumeric string that contains non-whitespace characters + and only hyphens, underscores, and periods. + +### bamptxid + +- Type: `String` +- Description: A unique identifier for the model of a transaction that + constructs a business process (e.g. payment, invoice, warehouse). +- Constraints + - REQUIRED + - MUST be a non-empty string + - RECOMMENDED a alphanumeric string that contains non-whitespace characters + and only hyphens, underscores, and periods. + +### bamptxsid + +- Type: `String` +- Description: A unique identifier for the specific step in a business process + transaction (e.g. start, processing, finish). +- Constraints + - REQUIRED + - MUST be a non-empty string + - RECOMMENDED a alphanumeric string that contains non-whitespace characters + and only hyphens, underscores, and periods. + +### bamptxsstatus + +- Type: `String` +- Description: The status of the specific step in a business process + transaction (e.g. success, waiting, failure). +- Constraints + - OPTIONAL + - if present, MUST be a non-empty string + - RECOMMENDED a alphanumeric string that contains non-whitespace characters + and only hyphens, underscores, and periods. + +### bamptxcompleted + +- Type: `Boolean` +- Description: Indicates if the instance of the transaction (`bamtxid`) has + actually been completed, or if the transaction has somehow failed. + This is a mechanism to indicate a final completion or failure that is + not captures by the model of the business process.. +- Constraints + - OPTIONAL + - if present, MUST be a boolean value + +## Usage + +When this extension is used, producers MUST set the value of +the `businesstransactionid`, `businessprocessid`, +`businessprocesstransactionid`, and `businessprocesstransactionstepid` +attributes to the unique identifiers of the business process, transaction, +and transaction step associated with the event. + +Intermediaries MUST NOT change the value of the `businesstransactionid`, +`businessprocessid`, `businessprocesstransactionid`, +and `businessprocesstransactionstepid` attributes. + +## Use cases + +This extension can be used in cases in which a business activity monitoring +system is used to monitor the progress of a business process, and the events +generated by the process are used to track the progress of the process. +Usually these systems have their own modelling language to describe the +business process, and the events generated by the process +are used to track the progress of the process. + +## References + +- [Gartner Business Activity Monitoring](https://www.gartner.com/en/information-technology/glossary/bam-business-activity-monitoring) +- [Business Activity Monitoring](https://en.wikipedia.org/wiki/Business_activity_monitoring) +- [What is Business Activity Monitoring (BAM)?](https://www.ibm.com/topics/business-activity-monitoring) +- [Business Activity Monitoring (BAM)](https://learn.microsoft.com/en-us/biztalk/core/business-activity-monitoring-bam) \ No newline at end of file diff --git a/cloudevents/languages/he/extensions/bam.md b/cloudevents/languages/he/extensions/bam.md new file mode 100644 index 00000000..3570ba88 --- /dev/null +++ b/cloudevents/languages/he/extensions/bam.md @@ -0,0 +1,2 @@ +# Business Activity Monitoring (BAM) Extension +מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/bam.md) לבינתיים. \ No newline at end of file diff --git a/cloudevents/languages/zh-CN/extensions/bam.md b/cloudevents/languages/zh-CN/extensions/bam.md new file mode 100644 index 00000000..333ce53c --- /dev/null +++ b/cloudevents/languages/zh-CN/extensions/bam.md @@ -0,0 +1,6 @@ +# Business Activity Monitoring (BAM) Extension + +本文档尚未被翻译，请先阅读英文[原版文档](../../../extensions/bam.md) 。 + +如果您迫切地需要此文档的中文翻译，请[提交一个issue](https://github.com/cloudevents/spec/issues) ， +我们会尽快安排专人进行翻译。 \ No newline at end of file