This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Aura entities definition in CSV

Aura entities definition in CSV format

Aura entities definition in CSV format version 5.0.0.

Introduction

The Aura entities definition includes the different entities currently written in Aura in CSV and required to calculate Aura KPIs or by any other team in their data processes.

Entities types Description Generation
Message Message entity is used to store information about the messages handled by aura-bot and the actions performed on them. They are created in aura-bot.
Recognizer Recognizer entity is used to store the request to any of the recognizers during the utterance recognition phase of the messages. They are created by aura-groot, aura-bot and aura-nlp.
Extended Message Extended Message entity is used to store extra information of a Message. They are created in aura-bot.
Groot Message Groot Message entity is used to store information about the messages handled by aura-groot. They are created in aura-groot.

Entities generation

Until release 9.3.0 (Gwen Stefani), all entities in Aura were generated in CSV format. They were also uploaded into Kernel storage in CSV format. Although using a script provided by and running in Kernel, some of them are converted to Avro entities (in a deprecated Avro format, not URM compliant).

In particular, the following conversions are provided:

As can be seen, the entities in Avro are duplicated to hold authenticated and anonymous users interactions separately, because the field USER_4P_ID cannot be null if it exists in a dataset definition.

CSV files format

All entities’ files must be created following these rules:

  • File format: UNIX. UTF8 without BOM
  • Date format: ISO8601
    • Date: 2018-05-02
    • Datetime: 2018-05-02T15:18:11Z => Always UTC

Usually, these kinds of files are stored in .txt and zipped, before uploading.

  • Entities used for the calculation of KPIs are stored in a Kernel bucket. Each entity must be included in a different folder, with files distributed by months, in the path:
    [OB]/[ENTITY]/YYYYMM

  • Files generated in aura-bot can be stored as needed.
    Filename: BOT_[HOST_ID]_[OB]_[ENTITY]_YYYYMMDDTHH0000Z.txt

  • Files generated in aura-services (authentication) can be stored as needed.
    Filename: SERVICES_[HOST_ID]_[OB]_[ENTITY]_YYYYMMDDTHH0000Z.txt

  • Files generated in Aura NLP components can be stored as needed:
    Filename: NLP_<HOST_ID>_<OB>_<ENTITY>_YYYYMMDDTHH0000Z.txt

  • Dimensions entities:
    Path: [OB]/DIMENSIONS/YYYYMM
    Filename: [OB]_DIM_[DIM_NAME]_YYYYMMDDTHH0000Z.txt
    For example: ES_DIM_CHANNEL_20180612T160000Z.txt

All the files are refreshed every day.

CSV Entities tables nomenclature

  • #: Field ID
  • FIELD: Specific field of the entity type
  • PK: Parameter that indicates if the field is a Primary Key or not, that is, a value that uniquely identifies this field.
  • NULLABLE: Parameter that indicates if a field is allowed to have a null value or not.
  • TYPE: Type of the field. It can be one of: text, date, number, boolean
  • DESCRIPTION: Brief description of the field
  • FORMAT: Field mandatory format, if applicable
  • ALLOWED VALUES: Prefixed values permitted for this field
  • EXAMPLE: Example of application

The following considerations must be taken into account:

  • Numeric values are rounded to two decimal positions
  • The amount of money must be included in local currency

1 - Aura_Gateway_Message

Aura_Gateway_Message v6.0.0

Within the different entities currently used in Aura, this document describes those included in the entity type Aura_Gateway_Message

NOTE: This entity is not used in production environments.

This entity contains the summary of Aura’s interactions handled by aura-gateway-api.

Position Field PK Referenced entity Referenced entity field Type Doc Nullable Doc
1 MESSAGE_ID YES string; x-fp-unique-constraint Unique ID of the current message.
2 MESSAGE_TM string;datetime Timestamp when the message is processed
3 AURA_APP_ID D_Aura_App AURA_APP_ID string;null Identifier of the Aura application used by the user to interact with Aura. If due to an error the application sent a wrongly formatted string without app_id, it will be set to null. It will be null if due to an error we are not capable of getting the incoming application.
4 COUNTRY_3_ALPHA_CD D_Gbl_Country COUNTRY_3_ALPHA_CD string Three letters (alpha-3) code element of the country name (e.g. DEU) defined in ISO 3166-1
5 CORR_ID string Cross service transaction identifier that allows tracking a request through all the services and components.
6 AURA_NLP_IND boolean Flag indicating whether or not this interaction goes to ATRIA NLP as a Service.
7 AURA_PRESET_NAME D_Aura_Preset AURA_PRESET_NAME string;null Configuration used by the app to access Aura AI services If it is a NLP access no preset will be defined
8 AURA_COMPONENT_HOST_ID string An identifier of the aura component host that handled the current request, usually the pod identifier running the corresponding aura service. This name changes every time a pod is reinitiated.
9 AURA_COMPONENT_ID D_Aura_Component AURA_COMPONENT_ID string An identifier of the aura component that handled the current request, usually the name of the deployment running the corresponding aura service. This name is consistent over time.
10 AURA_VERSION_ID string Aura platform version that produces this data.
11 DAY_DT string;iso-date;partition-key Year, month and day of the interaction
12 BRAND_ID D_Gbl_Brand GBL_BRAND_ID string Brand id. Join with D_Gbl_Brand
13 USER_ID string Identifier of the user sending the message YES

2 - Message

Message

Within the different entities currently used in Aura, this document describes those included in the entity type Message

# FIELD PK NULLABLE TYPE DESCRIPTION FORMAT ALLOWED VALUES EXAMPLE
1 USER_ID NO NO Text Unique User ID in the OB Systems or unique generated one for anonymous users Format depends on the OB —
2 MSG_DT NO NO Date Timestamp of the data in UTC time ISO 8601 —
3 MSG_ID YES NO Text Unique ID of the message UUID —
4 ACTION_CD NO NO Text Code of the action that produces the data — send, receive, event —
5 AURA_ID NO YES Text User logging ID in Aura
Starting in this version, the user will have a new aura_id each time she logs in Aura		 UUID —
6 PHONE_ID NO YES Text Phone number of the user Phone number including international prefix —
7 CHANNEL_CD NO YES Text Code of the channel where the action happened — Same values as AURA_CHANNEL_NAME field in the dimensional entity D_Aura_Channel
8 SUBSCRIPTION_CD NO YES Text Code of the subscription type of the user in the OB — PREPAID, POSTPAID, CONTROL —
9 DOMAIN_CD NO YES Text Code of the domain where the action happened
⚠️ Future use		 — —
10 CATEGORY_CD NO YES Text Code of the category where the action happened
⚠️ Future use		 — —
11 COUNTRY_CD NO NO Text ISO code of the country ISO 3166 —
12 CORR_ID NO NO Text Correlator ID of the request that produces the data UUID —
13 IS_CACHED NO NO Boolean It shows if the entity content was already cached or not — true/false —
14 STATUS_CD NO YES Text Status code of the action, if meaningful HTTP status code of the response —
15 REASON NO YES Text Result of the action in error case: error code — —
16 VERSION_ID NO NO Text Aura version that produces this data X.Y.Z — 8.2.0.
17 LANG_CD NO YES Text Language configured by the user for the communication - ISO 639 two-letter lowercase culture code
- ISO 3166 two-letter lowercase subculture code associated with a country or region		 —
18 TZ_CD NO NO Text Timezone where the communication happened UTC offset of the TZ. TZ codes —
19 DURATION_NU NO YES Number Duration of the action in milliseconds Natural number —
20 MESSAGE NO NO Text Content of the message — —
21 DIALOG_ID NO YES Text Id of the dialog where the message happens — —
22 CONVERSATION_ID NO NO Text Id of the conversation where the message happens UUID —
23 WIN_RECOGNIZER_CD NO YES Text Code of the recognizer that wins for this message Same values as AURA_RECOGNIZER_NAME field in the dimensional entity D_Aura_Recognizer
24 WIN_RECOGNIZER_SCORE_NU NO YES Number Score of the recognizer that wins for this message — —
25 INTENT NO YES Text Selected intent — —
26 ENTITIES NO YES Text List of entities determined by the recognizer — —
27 MODALITY_CD NO YES Text It explains how the user communicates with Aura — text, voice, form —
28 AURA_ID_GLOBAL NO YES Text It identifies the same user_id logged with the same authentication method — —
29 ACCOUNT_NUMBER NO YES Text Unique account number of the user
Mandatory only for Spain. But it can be null also in Spain because it is only available in aura-bot, not in aura-services		 — —

3 - Recognizer

Recognizer

Within the different entities currently used in Aura, this document describes those included in the entity type Recognizer

# FIELD PK NULLABLE TYPE DESCRIPTION FORMAT ALLOWED VALUES EXAMPLE
1 USER_ID NO NO Text Unique User ID in the OB Systems or unique generated one for anonymous users Format depends on the OB —
2 RECOGNIZER_DT NO NO Date Timestamp of the data in UTC time ISO 8601 —
3 RECOGNIZER_ID YES NO Text Unique ID of the recognizer UUID —
4 ACTION_CD NO NO Text Code of the action that produces the data — recognize —
5 AURA_ID NO YES Text User logging ID in Aura
Starting in this version, the user will have a new aura_id each time she logs in Aura.		 UUID —
6 PHONE_ID NO YES Text Phone number of the user Phone number including international prefix —
7 CHANNEL_CD NO YES Text Code of the channel where the action happened — Same values as AURA_CHANNEL_NAME field in the dimensional entity D_Aura_Channel
8 DOMAIN_CD NO YES Text Code of the domain where the action happened
⚠️ Future use		 — —
9 CATEGORY_CD NO YES Text Code of the category where the action happened
⚠️ Future use		 — —
10 COUNTRY_CD NO NO Text ISO code of the country ISO 3166 —
11 CORR_ID NO NO Text Correlator ID of the request that produces the data UUID —
12 IS_CACHED NO NO Boolean It shows if the entity content was already cached or not — true/false —
13 STATUS_CD NO YES Text Status code of the action, if meaningful HTTP status code of the response —
14 REASON NO YES Text Result of the action in error case: error code — —
15 VERSION_ID NO NO Text Aura version that produces the data X.Y.Z — 8.2.0.
16 LANG_CD NO YES Text Language configured by the user for the communication - ISO 639 two-letter lowercase culture code
- ISO 3166 two-letter lowercase subculture code associated with a country or region		 —
17 TZ_CD NO YES Text Timezone where the communication happened UTC offset of the TZ. TZ codes —
18 DURATION_NU NO NO Number Duration in milliseconds of the action Natural number —
19 SCORE_NU NO NO Number Score returned by the recognizer Real number from 0 to 1 —
20 INPUT NO YES Text User input sent to the recognizer
null if incoming message is an auraCommand		 — —
21 OUTPUT NO YES Text Complete output generated by the recognizer — —
22 INTENT NO YES Text Intent returned by the recognizer Format depends on the OB —
23 ENTITIES NO YES Text Entities returned by the recognizer due to the intent — —
24 COMMON_THRESHOLD_NU NO YES Number Common threshold used to determine the best answer of all recognizers Real number from 0 to 1 —
25 THRESHOLD NO YES Number Established threshold for the recognizer Real number from 0 to 1 —
26 EXPECTED_INTENT NO YES Text Intent expected to be returned by the recognizer — —
27 EXPECTED_ENTITIES NO YES Text Entities expected to be returned by the recognizer due to the intent — —
28 AURA_ID_GLOBAL NO YES Text It identifies the same user_id logged with the same authentication method — —
29 ACCOUNT_NUMBER NO YES Text Unique account number of the user
Mandatory only for Spain. But it can be null also in Spain because it is only available in aura-bot, not in aura-services		 — —

4 - Extended Message

Extended Message

Within the different entities currently used in Aura, this document describes those included in the entity type extended message

# FIELD PK NULLABLE TYPE DESCRIPTION FORMAT ALLOWED VALUES EXAMPLE
1 USER_ID NO NO Text Unique User ID in the OB Systems or unique generated one for anonymous users Format depends on the OB —
2 MSG_DT NO NO Date Timestamp of the data in UTC time ISO 8601 —
3 MSG_ID YES NO Text Unique ID of the message UUID —
4 ACTION_CD NO NO Text Code of the action that produces data — send, receive, event —
5 AURA_ID NO YES Text User logging ID in Aura
Starting in this version, the user will have a new aura_id each time she logs in Aura		 UUID —
6 PHONE_ID NO YES Text Phone number of the user Phone number including international prefix —
7 CHANNEL_CD NO YES Text Code of the channel where the action happened — Same values as AURA_CHANNEL_NAME field in the dimensional entity D_Aura_Channel —
8 SUBSCRIPTION_CD NO YES Text Code of the subscription type of the user in the OB — PREPAID, POSTPAID, CONTROL —
9 DOMAIN_CD NO YES Text Code of the domain where the action happened
⚠️ Future use		 — —
10 CATEGORY_CD NO YES Text Code of the category where the action happened
⚠️ Future use		 — —
11 COUNTRY_CD NO NO Text ISO code of the country ISO 3166 —
12 CORR_ID NO NO Text Correlator ID of the request that produces the data UUID —
13 IS_CACHED NO NO Boolean It shows if the entity content was already cached or not — true/false —
14 STATUS_CD NO YES Text Status code of the action, if meaningful HTTP status code of the response —
15 REASON NO YES Text Result of the action in error case: error code — —
16 VERSION_ID NO NO Text Aura version that produces this data X.Y.Z — 8.2.0.
17 LANG_CD NO YES Text Language configured by the user for the communication - ISO 639 two-letter lowercase culture code
- ISO 3166 two-letter lowercase subculture code associated with a country or region		 —
18 TZ_CD NO NO Text Timezone where the communication happened UTC offset of the TZ. TZ codes —
19 DURATION_NU NO YES Number Duration of the action in milliseconds Natural number —
20 MESSAGE NO NO Text Content of the message — —
21 DIALOG_ID NO YES Text Id of the dialog where the message happens — —
22 CONVERSATION_ID NO NO Text Id of the conversation where the message happens UUID —
23 WIN_RECOGNIZER_CD NO YES Text Code of the recognizer that wins for this message Same values as AURA_RECOGNIZER_NAME field in the dimensional entity D_Aura_Recognizer
24 WIN_RECOGNIZER_SCORE_NU NO YES Number Score of the recognizer that wins for this message — —
25 INTENT NO YES Text Selected intent — —
26 ENTITIES NO YES Text List of entities determined by the recognizer — —
27 MODALITY_CD NO YES Text It explains how the user communicates with Aura — text, voice, form —
28 AURA_ID_GLOBAL NO YES Text It identifies the same user_id logged with the same authentication method — —
29 ACCOUNT_NUMBER NO YES Text Unique account number of the user
Mandatory only for Spain. But it can be null also in Spain because it is only available in aura-bot, not in aura-services		 — —

5 - Groot message

Groot message

Within the different entities currently used in Aura, this document describes those included in the entity type groot message

# FIELD PK NULLABLE TYPE DESCRIPTION FORMAT ALLOWED VALUES EXAMPLE
1 USER_ID NO NO Text Unique User ID in the OB Systems or unique generated one for anonymous users Format depends on the OB —
2 MSG_DT NO NO Date Timestamp of the data in UTC time ISO 8601 —
3 MSG_ID YES NO Text Unique ID of the message UUID —
4 ACTION_CD NO NO Text Code of the action that produces data — send, receive, event —
5 AURA_ID NO YES Text User logging ID in Aura
Starting in this version, the user will have a new aura_id each time she logs in Aura		 UUID —
6 PHONE_ID NO YES Text Phone number of the user Phone number including international prefix —
7 CHANNEL_CD NO YES Text Code of the channel where the action happened — Same values as AURA_CHANNEL_NAME field in the dimensional entity D_Aura_Channel —
8 DOMAIN_CD NO YES Text Code of the domain where the action happened
⚠️ Future Use		 — —
9 CATEGORY_CD NO YES Text Code of the category where the action happened
⚠️ Future Use		 — —
10 COUNTRY_CD NO NO Text ISO code of the country ISO 3166 —
11 CORR_ID NO NO Text Correlator ID of the request that produces data UUID —
12 IS_CACHED NO NO Boolean It shows if the entity content was already cached or not — true/false —
13 STATUS_CD NO YES Text Status code of the API request HTTP status of the response —
14 REASON NO YES Text Result of the action in error case: error code — —
15 VERSION_ID NO NO Text Aura version that produces data X.Y.Z — 8.2.0.
16 LANG_CD NO YES Text Language configured by the user for the communication - ISO 639 two-letter lowercase culture code
- ISO 3166 two-letter lowercase subculture code associated with a country or region		 —
17 TZ_CD NO YES Text Timezone where the communication happened UTC offset of the TZ. TZ codes —
18 DURATION_NU NO NO Number Duration in milliseconds of the action Natural number
19 MESSAGE NO NO Text Content of the message — —
20 CHANNEL_CONVERSATION_CD NO NO Text Identifier of the conversation in the channel (conversationId in aura-groot) — —
21 SKILL_CONVERSATION_CD NO NO Text Identifier of the conversation in the skill — —-
22 WIN_RECOGNIZER_CD NO YES Text Code of the recognizer that wins for this message — Same values as AURA_RECOGNIZER_NAME field in the dimensional entity D_Aura_Recognizer
23 WIN_RECOGNIZER_SCORE_NU NO YES Number Score of the recognizer that wins for this message — —
24 AURA_ID_GLOBAL NO YES Text It identifies the same user_id logged with the same authentication method — —
25 ACCOUNT_NUMBER NO YES Text Unique account number of the user
Mandatory only for Spain, but it can be null also in this country because it is only available in aura-bot, not in aura-services		 — —
26 SKILL_CD No No Text Identifier of the skill — Same values as AURA_SKILL_NAME field in the dimensional entity D_Aura_Skill
27 AURA_COMPONENT_ID No No Text Identifier of the Aura component — Same values as AURA_COMPONENT_NAME field in the dimensional entity D_Aura_Component
28 AURA_COMPONENT_HOST_ID No No Text Identifier of the host running the specific component —
29 BRAND_ID No No Text Identifier of the Telefonica’s brand — Same values as BRAND_ID field in D_GBL_BRAND