Embed Athena#

Embed Athena stands out as a robust feature tailored for scenarios in which organizations aim to seamlessly incorporate Athena into their proprietary applications rather than directly accessing the ConverSight platform. This functionality is of utmost value, providing users with the ability to meticulously customize access through the application of filters, thereby tailoring it to specific users and facilitating the convenient retrieval of data from any location. Particularly advantageous for users lacking ConverSight access, Embed Athena empowers individuals by equipping them with the capability to harness the complete potential of data visualization and analysis in their daily workflow.

Incorporating Athena into chosen applications guarantees a refined user experience, facilitating the effortless viewing of Athena chat within preferred tools or systems, thereby enhancing overall accessibility. This feature ensures that the shared members can gain a comprehensive understanding of your Athena chat, including filters, preferences, and interactions, providing a detailed and accurate representation of your experience within the platform. In essence, the utilization of Embed Athena offers unparalleled flexibility in accessing and interacting with real-time data, nurturing informed decision-making irrespective of the user’s location. Consequently, it emerges as an invaluable tool for organizations seeking to optimize their data utilization strategies.

To access Embed Athena, click on the Profile icon in the ConverSight platform.

Choose the Embed Athena option.

To Embed Athena, you can follow these steps:

We implement two security access types when embedding Athena,

Embed Athena as Public
Embed Athena as Private

Embed Athena as Public#

Configuring Embed Athena as public entails granting access to the Athena instance for anyone. This setting actively cultivates a culture of collaboration and knowledge sharing by enabling individuals, regardless of their specific roles or permissions, to readily access and engage with the content. This configuration is particularly advantageous for organizations seeking to promote widespread data utilization and collaboration across diverse teams.

Steps to Embed Athena as Public:#

Step 1: Upon selecting the Embed Athena option, a code snippet will be presented. To proceed, click on the Generate Token option.

Step 2: The Generate Token page for Embed Athena provides users with the flexibility to define the validity period of the embedded Athena instance, offering two options:

Never: Selecting the Never option denotes that the Athena instance is free from any temporal constraints, ensuring continuous and unrestricted accessibility without an expiration date. This choice is suitable for scenarios demanding constant access to the embedded Athena without imposing temporal limitations.
Expiry: Opting for the Expiry option empowers users to define a specific duration in days, week or months for accessing the Embedded Athena. By setting an expiry time, users gain control over the timeframe during which others can access and utilize the designated Athena instance. This feature proves advantageous when there is a requirement to restrict access to the embedded Athena within a defined time period, offering a level of control and security over the accessed data or information.

Step 3: Select Insights from those you have created.

Step 4: Select the security access type as Public and designate your preferred domain.

../_images/Public6.png — Access Type and Domain#

NOTE
Users have the option to include multiple domain names, but it is mandatory for them to include at least one domain name.

Step 5: After entering all essential information, proceed to click on the Submit button to generate the authToken and accessID within the code snippet.

../_images/Public8.png — AuthToken and AccessID#

Step 6: To copy the snippet, simply click on the Copy icon positioned adjacent to the code, this action will automatically copy the code to the user’s clipboard.

../_images/Public8_1.png — Copy Snippet#

Step 7: After copying the Embed Athena snippet, effortlessly insert it into applications that accommodate HTML code. Subsequently, save the snippet as an HTML file, a standard format for web pages compatible with web browsers. This ensures universal access for anyone with an internet connection, regardless of the device or platform used, enabling seamless integration across various environments, be it in a website builder, content management system or a simple text editor.

Step 8: Following the successful integration of the code snippet, users have the capability to initiate the launch of Athena chat directly from the customer platform. This functionality eliminates the need for users to navigate between different platforms, thereby enhancing overall usability and convenience. Notably, users can view the same Athena chat shared by others even without logging in the ConverSight platform, adding an extra layer of accessibility and ease of use.

Embed Athena as Private#

In a Private security, access type is managed at the user level through assigned filter values and column names. These are determined by the User Token generated via the User Provision API on the customer’s end. Users have varying access levels based on roles. This role-based access control enhances data privacy and security, limiting access to sensitive information. Organizations can tailor user experiences, aligning with specific roles, to boost productivity while safeguarding sensitive data.

Steps to Embed Athena as Private:#

Step 1: Upon selecting the Embed Athena option, a code snippet will be presented. To proceed, click on the Generate Token option.

Step 2: The Generate Token page for Embed Athena provides users with the flexibility to define the validity period of the embedded Athena instance, offering two options:

Never: Selecting the Never option denotes that the Athena instance is free from any temporal constraints, ensuring continuous and unrestricted accessibility without an expiration date. This choice is suitable for scenarios demanding constant access to the embedded Athena without imposing temporal limitations.
Expiry: Opting for the Expiry option empowers users to define a specific duration in days, week or months for accessing the Embedded Athena. By setting an expiry time, users gain control over the timeframe during which others can access and utilize the designated Athena instance. This feature proves advantageous when there is a requirement to restrict access to the embedded Athena within a defined time period, offering a level of control and security over the accessed data or information.

Step 3: Select Insights from those you have created.

Step 4: Select the security access type as Private and designate your preferred domain.

../_images/Private10b.png — Access Type and Domain#

NOTE
Users have the option to include multiple domain names, but it is mandatory for them to include at least one domain name.

Step 5: After entering all required details, select the Submit button to generate the authToken and accessID within the snippet. It is essential for the user to securely retain the accessID for future reference and use.

../_images/Private12.png — AuthToken and AccessID#

Step 6: To duplicate the snippet, simply click on the Copy icon beside the code, automatically copying the code to the user’s clipboard.

../_images/Private12_1.png — Copy Snippet#

Step 7: Embed the supplied code snippet into the designated customer platform, making sure that the ConverSight launch component is uncommented and equipped with the User Token as an argument. This User Token acts as the authentication key, providing users with the essential permissions and privileges to access the Embedded Athena.

Step 8: The creation of the User Token involves utilizing the User Provision API and the organization token. This unique identifier, exclusively generated by the system administrator at ConverSight, is known as Orgtoken. Each organization is assigned its own Orgtoken, serving as a crucial key for authenticating and accessing various organizational functionalities and resources. The generated Access ID from the snippet is also employed in this process.

To generate the user token, it is imperative to provide essential details, such as the dataset and role-specific filters, to the user in the API body. These filters enable the restriction of access to specific columns or the application of conditions to columns. Additionally, they facilitate the inclusion of multiple dataset access for a single user. These details ensure that the user is granted appropriate access and permissions within the system.

NOTE
The User Provision API is utilized to create and update user access.

User Provision Request:

URL: https://app.conversight.ai/api/v1/user/provision?token= Org AccessToken

Request:  
    {  
 
    "expiry": {  
 
            "frequency": "days",  
 
            "value": 1  
 
        },  
        "email": "<<email>>",  
 
        "firstName": "<<firstName>>",  
 
        "lastName": "<<lastName>>",  
 
        "displayName": "<<displayName/Alias>>",  
 
        "accessID": "<<accessID>>",  
 
        "roles": [  
 
            {  
                "name": "<<roleName>>",  
 
                "dataset": "<<datasetID>>",  
                
                "configuration": {

                                "currency": "<<currency>>",

                                "financialOffset": <<num>>
                        },

                "filters": [  
 
                    {  
                         "column": "<<columnName>>",  
 
                        "operator": "<<operator>>",  
 
                        "value": [  
 
                            "<<valuesToFilter>>"  
 
                        ] } ] } ] }  
 
    Response:  
 
    Success Response:  
    
    HTTP Status code -> 200  
    {  
        "status": "success",  
        "data": {  
 
            "token": "<<userLevelAccessToken>>",  
 
            "id": "<<userID>>"  
 
        }  
 
    }  
 
    Failure Response:  
 
    HTTP Error code -> 401, 400, 403, 500  
 
    {  
 
        "status": "failed",  
 
        "error": "<<errorMessage>>"  
 
    }

The provided HTTP request necessitates specific fields:

firstName: The user’s first name intended for provisioning.
lastName: The user’s last name intended for provisioning.
displayName: The preferred display name or alias chosen by the user.
email: The email address of the user intended for provisioning.
roles: Roles include details such as the role name, dataset ID, configurations (including currency format and financial year settings), and the related filters. These role details are crucial for ensuring controlled data visibility and security.

Moreover, the filter in the roles is an optional field. If left empty, the user will be granted full access. It is crucial to maintain the details within the request unaltered. Additionally, when generating the token, be sure to include the generated accessID.

NOTE
If the frequency is set as Never then the value will be -1.

Step 8: Upon receiving a response from the User Provision API, it will furnish a User Token and a User ID. It is imperative to securely store these generated tokens within the customer platform for subsequent use. The User Token obtained from the response should be presented as an argument in the ConverSight.launch(<< user token >>) method within the snippet. This ensures proper authentication of the user, granting them suitable access to the embedded functionality within the ConverSight platform.

Step 9: Following the successful integration of the snippet, users can initiate the launch of Athena directly from the customer platform. If a user lacks an existing account with ConverSight, account creation can be accomplished either on the ConverSight platform or by utilizing their API from the customer’s platform, incorporating filter values for roles and datasets. Once the account is established, the user gains the ability to access and interact with the Athena directly from their own platform, ensuring a seamless experience.

The Embed Athena servers, for those without an existing ConverSight account, the flexibility exists to create an account either on the ConverSight platform or by leveraging their API from the customer’s platform, with the inclusion of filter values for roles and datasets. Once the account is established, users acquire the capability to access and interact with the Athena directly from their own platform, providing a streamlined and user-friendly experience. This comprehensive process ensures efficient utilization of ConverSight’s features while accommodating users at various levels of engagement.

For any queries, please get in touch with our support team at info@conversight.ai.