AWS connect: Data tables docs: access control, lock levels, expressions
Summary
Rewrites and expands the AWS Connect data tables admin guide, adding default values, lock levels, CSV import/export, expressions, and updated access control/record-based access control guidance.
Security assessment
The diff documents access control mechanisms (security profiles, record-based access control) and permissions for expressions, but does not reference a specific vulnerability, CVE, or incident.
Evidence
+ * Record-based access control restricts a user to specific records (rows) within a table, based on primary attribute values. You configure it on a [security profile](./connect-security-profiles.html) by specifying primary attributes and the values that a user can access. Any data table that contains a primary attribute with a matching name is then restricted to the records that have those primary values. Use record-based access control when multiple teams need to access different subsets of data within large, multi-purpose tables. For more information, see [Apply record-based access control in Connect Customer](./record-based-access-control.html).
Diff
diff --git a/connect/latest/adminguide/data-tables.md b/connect/latest/adminguide/data-tables.md index e1f0faed6..75cfdbaae 100644 --- a//connect/latest/adminguide/data-tables.md +++ b//connect/latest/adminguide/data-tables.md @@ -7 +7 @@ -Understanding data tablesCreate data tablesAdd records to data tablesEdit data tables and their recordsSample use caseUsing data tables for dynamic lookups in flowsUse data tables to build custom user interfacesAccess control and security for data tablesService quotas for data tablesTrack changes to data tables +What are data tables?Sample use caseCreate data tablesAdd records to data tablesEdit data tables and their recordsDefault valuesPrevent conflicting edits with lock levelsImport and export data table valuesData table expressionsUsing data tables for dynamic lookups in flowsUse data tables to build custom user interfacesAccess control and security for data tablesService quotas for data tablesTrack changes to data tables @@ -11 +11 @@ Understanding data tablesCreate data tablesAdd records to data tablesEdit data t -## Understanding data tables +## What are data tables? @@ -13 +13 @@ Understanding data tablesCreate data tablesAdd records to data tablesEdit data t -With data tables, you can store and manage data that affects your configurations within Connect Customer. Data tables can be referenced by other resources, such as flows and views. When changes or additions are made to data tables, they are available immediately through public APIs and on-screen, no redeployment necessary. +With data tables, you can store and manage data that affects your configurations within Connect Customer. You define their structure as attributes (columns) and values (rows), with validation rules that enforce data integrity. Other resources, such as flows and views, reference that data at runtime. For example, a flow can read a value to decide how to route a contact, and a view can display a value to an agent. The data lives in the table rather than in the resources that use it, so you can change a value directly, and the update takes effect immediately. @@ -15 +15 @@ With data tables, you can store and manage data that affects your configurations -Use data tables to support scenarios ranging from simple routing rules to complex, time-based configurations, accessible and modifiable in real time. In contrast to [Predefined Attributes](./predefined-attributes.html) which store simple key-value pairs, data tables support multiple columns, various data types, and complex relationships. +Data tables support use cases that range from simple routing rules to complex, time-based configurations, all editable in real time. Unlike [predefined attributes](./predefined-attributes.html), which store a named list of values, a data table can have multiple columns, a range of data types, and references between tables. @@ -17 +17,3 @@ Use data tables to support scenarios ranging from simple routing rules to comple -For example, you can create a data table that maps each store location to its business hours and support queue. In a flow, you look up the caller's location in the table and route the contact based on whether the store is open. Because you update the table directly, you can change hours or queues without editing the flow. +For example, a data table can map each store location to its business hours and support queue. A flow can look up the caller's location in the table and route the contact based on whether that store is open. You update the table directly, so you can change hours or queues without editing the flow, and without granting access to sensitive flow resources. + +In addition to entering a value directly, you can calculate it with an expression. For example, an expression can return a morning or afternoon greeting based on the current time, or look up a value in another data table. Expressions are evaluated when the value is read, so the result stays current. For more information, see Data table expressions. @@ -34,2 +35,0 @@ Table metadata includes: - * Optional default values that can be applied across records - @@ -42,0 +43,37 @@ Table values are stored in records (rows) that contain values for each attribute +## Sample use case + +The following example builds a simple translations table that stores a prompt for each language. + + 1. Create a data table with a primary attribute named `Language`. The primary attribute is the key used to look up a record in the table. + + 2. Add an attribute for each message type, such as `Greeting`. To support a large number of message types, use the advanced example that follows, which adds primary attributes instead of a separate column for each message type. + + 3. Add a record for each language. + + + + +The table looks like this: + +Language (primary attribute) | Greeting +---|--- +English | Hello +Spanish | Hola + +To look up a value along more than one dimension, add more primary attributes. For example, a `Department` primary attribute lets each greeting vary by both language and department. + +Language (primary attribute) | Department (primary attribute) | Greeting +---|---|--- +English | Sales | Hello. This is sales. +Spanish | Sales | Hola. Soy del departamento de ventas. +English | Marketing | Hi. You've reached marketing. + +Add a third primary attribute, `Message type`, to identify each message precisely. + +Language (primary attribute) | Department (primary attribute) | Message type (primary attribute) | Message +---|---|---|--- +English | Sales | Greeting | Hello. This is sales. +Spanish | Sales | Greeting | Hola. Soy del departamento de ventas. +English | Marketing | Greeting | Hi. You've reached marketing. +English | Marketing | Farewell | Thanks for contacting marketing. + @@ -45 +82 @@ Table values are stored in records (rows) that contain values for each attribute - 1. Go to the Routing menu and select **Data tables**. + 1. Go to the Routing menu and choose **Data tables**. @@ -47 +84 @@ Table values are stored in records (rows) that contain values for each attribute - 2. Select **Add new data table**. + 2. Choose **Add new data table**. @@ -57 +94 @@ Table values are stored in records (rows) that contain values for each attribute - 3. After saving, select Add attribute to define the first column in the table. + 3. After saving, choose **Add attribute** to define the first column of the table. @@ -61 +98 @@ Table values are stored in records (rows) that contain values for each attribute -As attributes are added, they are inserted into the table in the leftmost column. +Primary attributes appear first, followed by the other attributes. Within each group, attributes are sorted alphabetically by name. @@ -63 +100 @@ As attributes are added, they are inserted into the table in the leftmost column - 1. Provide a **Name** + 1. Provide a **Name**. @@ -65 +102 @@ As attributes are added, they are inserted into the table in the leftmost column - 2. Select a **Type** , choosing from + 2. Choose a **Type** : @@ -67 +104 @@ As attributes are added, they are inserted into the table in the leftmost column - 1. **Single** text, number or boolean (yes/no) attribute + 1. **Single** text, number, or boolean (yes/no) attribute @@ -71 +108 @@ As attributes are added, they are inserted into the table in the leftmost column - 3. (Optional) Select **Use as primary attribute**. + 3. (Optional) Choose **Use as primary attribute**. @@ -77 +114 @@ As attributes are added, they are inserted into the table in the leftmost column -Primary attributes cannot be added or removed if the table contains data. For example, if a table's primary attributes are first name, last name and middle initial, you cannot add SSN as another primary attribute or remove middle initial, without first deleting all rows. However, you can edit the values in a primary attribute, for example a last name can be changed. You can also add non-primary attributes after a table is populated with data. +Primary attributes cannot be added or removed if the table contains data. For example, if a table's primary attributes are first name, last name, and middle initial, you cannot add SSN as another primary attribute or remove middle initial without first deleting all records. However, you can edit the values in a primary attribute, for example a last name can be changed. You can also add non-primary attributes after a table is populated with data. @@ -83 +120 @@ Primary attributes cannot be added or removed if the table contains data. For ex - 6. Upon saving, your table will display with its first attribute (column). + 6. Upon saving, your table displays its first attribute (column). @@ -87 +123,0 @@ Primary attributes cannot be added or removed if the table contains data. For ex - 4. When ready, select **Add value** to insert a row into your table. @@ -89 +124,0 @@ Primary attributes cannot be added or removed if the table contains data. For ex - 1. When adding the first value, you must acknowledge that primary attributes cannot be changed if values exist in the table. @@ -91 +125,0 @@ Primary attributes cannot be added or removed if the table contains data. For ex - 2. Data inputs are automatically validated (type, length). @@ -93 +127 @@ Primary attributes cannot be added or removed if the table contains data. For ex - 3. As values are added, they are sorted based on primary value(s), for example if the first column is text, the values (rows) will be sequenced from A-Z. + @@ -94,0 +129 @@ Primary attributes cannot be added or removed if the table contains data. For ex +## Add records to data tables @@ -95,0 +131 @@ Primary attributes cannot be added or removed if the table contains data. For ex +A record is a row of values in a data table. How you add a record depends on whether the table has primary attributes. When you add or edit a record, Connect Customer enforces the required fields, data types, length limits, and other validation rules specified in the table definition. @@ -96,0 +133 @@ Primary attributes cannot be added or removed if the table contains data. For ex +For data tables with primary attributes, each record is uniquely identified by its primary values. To add a record, choose **Add record** , and then enter the primary values along with the value for each attribute. These tables also have a default record, which provides the values that are returned when a lookup does not match a record. To set the default record, choose the actions menu (the ellipsis icon) on the first (default) record, and then choose **Edit default record**. @@ -98 +135 @@ Primary attributes cannot be added or removed if the table contains data. For ex - +Data tables without primary attributes can contain only one record, which is the default record. Choose **Add record** to set the values of the default record. @@ -100 +137 @@ Primary attributes cannot be added or removed if the table contains data. For ex -Example of a table structure where two primary attributes are used to uniquely identify each record, and two attributes have been defined. +When you add the first record, you must confirm that the table's primary attributes can no longer be changed once it contains data. Connect Customer sorts records by their primary values; for example, when the first primary attribute is text, records are ordered alphabetically. @@ -102,5 +139 @@ Example of a table structure where two primary attributes are used to uniquely i -Primary Attribute 1 | Primary Attribute 2 | Attribute 1 | Attribute 2 ----|---|---|--- -Primary Value | Primary Value | Value | Value -Primary Value | Primary Value | Value | Value -... | ... | ... | ... +For more information about default records and the values that Connect Customer returns when a lookup does not match a record, see Default values. @@ -108 +141,5 @@ Primary Value | Primary Value | Value | Value -## Add records to data tables +## Edit data tables and their records + +You can edit a data table's records at any time, and you can change most of its structure. After a data table contains data, you cannot add or remove primary attributes, but you can rename them and add non-primary attributes. When you save a change, Connect Customer validates it against the table definition, enforcing the same required fields, data types, and length limits that apply when you add a record. To keep multiple editors from overwriting each other's changes, you can lock edits. For more information, see Prevent conflicting edits with lock levels. + +To edit a single value, choose its cell in the table and enter the new value. To add a whole record, choose **Add record**. To edit the table's default record, choose the actions menu (the ellipsis icon), and then choose **Edit default record**. @@ -110 +147,5 @@ Primary Value | Primary Value | Value | Value -Connect Customer enforces required fields, data types, length limits and other requirements specified in the table definition. +Changes take effect almost immediately. An update applies to later flow runs and API calls, and flows do not cache table data, so no refresh is required after a change. + +###### Note + +While changes propagate rapidly, in rare cases, there might be a brief delay, typically just milliseconds, before all system components reflect the change. When feasible, plan updates during operational windows to minimize impact. @@ -116 +157 @@ Always test configurations that impact flows before impacting production workloa -## Edit data tables and their records +## Default values @@ -118 +159 @@ Always test configurations that impact flows before impacting production workloa -Connect Customer enforces required fields, data types, length limits and other requirements specified in the table definition. +A data table always returns a value that conforms to the attribute's type, so resources that reference the table, such as flows and views, always receive a usable value. Connect Customer provides this guarantee through two levels of defaults: a default record that supplies fallback values when a lookup does not match a record, and a built-in default for each value type. When a value is requested, Connect Customer resolves it in the following order: @@ -120 +161 @@ Connect Customer enforces required fields, data types, length limits and other r -**Safeguards are provided for simultaneous edits to the same data.** The system automatically alerts users when changes occur outside their current session, prompting them to refresh their view to see the latest data. + 1. If the requested record contains a value for the attribute, that value is returned. @@ -122 +163 @@ Connect Customer enforces required fields, data types, length limits and other r -###### Note + 2. If the requested primary values do not match a record, the value from the default record is returned. @@ -124 +165 @@ Connect Customer enforces required fields, data types, length limits and other r -For scenarios where preventing conflicts is critical, you can implement optimistic locking strategies, making sure that updates are only applied if the data hasn't changed since it was last read. + 3. If the default record does not define the attribute, or the data table has no default record, the default for the attribute's value type is returned. @@ -126 +166,0 @@ For scenarios where preventing conflicts is critical, you can implement optimist -**Changes take place _almost_ immediately**. Changes made to data tables take effect in subsequent flow executions and API calls. Data is not cached in flows, so there is no lag required for refresh after a change. @@ -128 +167,0 @@ For scenarios where preventing conflicts is critical, you can implement optimist -###### Note @@ -130 +168,0 @@ For scenarios where preventing conflicts is critical, you can implement optimist -While changes propagate rapidly, in rare cases, there might be a brief delay, typically just milliseconds, before all system components reflect the change. When feasible, plan updates during operational windows to minimize impact. @@ -132 +170,9 @@ While changes propagate rapidly, in rare cases, there might be a brief delay, ty -## Sample use case +The following table lists the default for each value type. + +Value type | Default value +---|--- +Text | Empty string (`""`) +Number | `0` +Boolean | `false` +Text list | Empty list (`[]`) +Number list | Empty list (`[]`) @@ -134 +180 @@ While changes propagate rapidly, in rare cases, there might be a brief delay, ty -Follow these steps to create a simple translations table for prompts. +For example, consider a data table with a `Language` primary attribute and a `Greeting` attribute. @@ -136 +182,4 @@ Follow these steps to create a simple translations table for prompts. - 1. Create a new data table with a new primary attribute called “Language”. The primary attribute determines the key needed to access a record from the data table. +Language (primary attribute) | Greeting +---|--- +(Default) | Hello +Spanish | Hola @@ -138 +187 @@ Follow these steps to create a simple translations table for prompts. - 2. Create a new attribute for each message type, “Greeting” for example. If you need to create more than 99 types of messages, see the advanced example that follows. +A lookup for `Spanish` returns `Hola`. A lookup for a language that has no record, such as `French`, returns the default record's value, `Hello`. If the data table had no default record, the same lookup would return an empty string, which is the default for the text value type. @@ -140 +189 @@ Follow these steps to create a simple translations table for prompts. - 3. Add the translations to your table. +The default record supplies the fallback value for each attribute. To set these values, choose the actions menu (the ellipsis icon), and then choose **Edit default record**. If a data table has no primary attributes, it contains only the default record; choose **Add record** to set its values. For more information, see Add records to data tables. @@ -142 +191 @@ Follow these steps to create a simple translations table for prompts. - 4. Your table should look like this: +As a result, a data table never returns a null value. Every attribute always resolves to a value of its declared type. @@ -143,0 +193 @@ Follow these steps to create a simple translations table for prompts. +## Prevent conflicting edits with lock levels @@ -144,0 +195 @@ Follow these steps to create a simple translations table for prompts. +Data table values can be updated at any time by multiple people and automated processes, including flows and API calls. To prevent one editor from unintentionally overwriting another editor's changes, each data table has a **lock level**. You set the lock level when you create a data table, and you can change it at any time. @@ -145,0 +197 @@ Follow these steps to create a simple translations table for prompts. +Locking is optimistic. Reading values is never blocked. An update is applied only if no conflicting change was made within the locked scope since the values were last read. If a conflicting change occurred, the update is rejected, and the editor must refresh to load the latest values before trying again. The lock level determines the scope at which a concurrent change blocks an update. @@ -147 +199 @@ Follow these steps to create a simple translations table for prompts. -Language (primary attribute) | Greeting +Lock level | Behavior @@ -149,2 +201,5 @@ Language (primary attribute) | Greeting -English | Hello -Spanish | Hola +Data table | An update is rejected if any value in the table changed since the values were last read. This is the most restrictive lock level, and effectively allows only one editor to change the table at a time. +Record (row) | An update is rejected if any value in the same record changed. Edits to different records can proceed at the same time. If the table has no primary attributes, it contains a single record, so this lock level behaves like the data table lock level. +Attribute (column) | An update is rejected if any value for the same attribute changed. Edits to different attributes can proceed at the same time. +Value (cell) | An update is rejected only if that same value changed. Edits to any other value can proceed at the same time. This is the least restrictive lock level that still prevents overwrites.