From c03c2d019adcc713d44f3eab58da694d1aba6a61 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 11:19:50 -0600 Subject: [PATCH 01/22] docs: Clarify first few steps --- README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 4d10265..5de2ce0 100644 --- a/README.md +++ b/README.md @@ -16,22 +16,24 @@ ### Setup -1. Install nodejs https://nodejs.org/en/download/ +1. Install Node (https://nodejs.org/en/download/) -2. Install yarn - https://yarnpkg.com/en/docs/install +2. Install yarn (https://yarnpkg.com/en/docs/install) 2. Locate or create the dashboard or card that you would like to embed in Domo. 3. Embed the card or dashboard using the 'Private' Embed option. -4. In the base folder of the repository run yarn to install the necessary dependencies. +4. Clone or download this repository. + +5. In the base folder of the repository run yarn to install the necessary dependencies. ``` - # yarn + yarn ``` -5. Modify the existing file in the base folder of the project named .env +6. Modify the existing file in the base folder of the project named .env -6. Inside of this file change the following configuration settings but using your own values: +7. Inside of this file change the following configuration settings but using your own values: ``` CLIENT_ID=YOUR_CLIENT_ID CLIENT_SECRET=YOUR_CLIENT_SECRET @@ -69,12 +71,12 @@ The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. -7. Start the express server like this in the base folder of the project +8. Start the express server like this in the base folder of the project ``` # yarn start ``` -8. An alternate port can be specified to start the program on by adding -p number to the end of the yarn start command like this: +9. An alternate port can be specified to start the program on by adding -p number to the end of the yarn start command like this: ``` # yarn start -p 3002 ``` From 63c6b3528a125f0ffe4a58299e06f17a0a1fec11 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 11:28:41 -0600 Subject: [PATCH 02/22] docs: Move docs next to key Instead of having them all above, I figured it would be clearer to have them next to the one they are referring to. --- README.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 5de2ce0..7c203d3 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ yarn ``` -6. Modify the existing file in the base folder of the project named .env +6. Modify the existing file in the base folder of the project named `.env` 7. Inside of this file change the following configuration settings but using your own values: ``` @@ -40,22 +40,20 @@ EMBED_ID=YOUR_EMBED_ID EMBED_TYPE=dashboard - # optional settings + # Optional settings USE_XHR=true REPLACE_IFRAME=true EMBED_ID{X}=YOUR_EMBED_ID - # optional settings for testing the Domo Everywhere edit experience; routing users to specific instances. For more information on the Edit experience, see here: https://domo-support.domo.com/s/article/6523741250455?language=en_US + # Optional settings for testing the Domo Everywhere edit experience; routing users to specific instances. For more information on the Edit experience, see here: https://domo-support.domo.com/s/article/6523741250455?language=en_US + # --- # The Embed URL for Identity Broker is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing - # The KEY_ATTRIBUTE variable name is defined in Domo under Admin -> Deomo Everywhere -> Embed -> Mapping - # The MAPPING_VALUE is defined for each instance. Verify the value in the MAPPING_VALUE variable below matches the associated name in the "Attibute Value" colummn for the target organization at Admin -> Domo Everywhere -> Embed -> Mapping IDP_URL=HTTPS://YOUR_IDP_URL.domo.com JWT_SECRET = YOUR_JWT_SECRET + # The KEY_ATTRIBUTE variable name is defined in Domo under Admin -> Deomo Everywhere -> Embed -> Mapping KEY_ATTRIBUTE = keyAttributeName + # The MAPPING_VALUE is defined for each instance. Verify the value in the MAPPING_VALUE variable below matches the associated name in the "Attibute Value" colummn for the target organization at Admin -> Domo Everywhere -> Embed -> Mapping MAPPING_VALUE = XXXXXXXXXXXXXX - - - ``` The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. From ae041aa84949e53b66a678225ac1bdc9d4397f1d Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 11:37:36 -0600 Subject: [PATCH 03/22] docs: Specify which type of file to get syntax highlighting --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7c203d3..988f1b0 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ 6. Modify the existing file in the base folder of the project named `.env` 7. Inside of this file change the following configuration settings but using your own values: - ``` + ```properties CLIENT_ID=YOUR_CLIENT_ID CLIENT_SECRET=YOUR_CLIENT_SECRET EMBED_ID=YOUR_EMBED_ID @@ -52,7 +52,7 @@ JWT_SECRET = YOUR_JWT_SECRET # The KEY_ATTRIBUTE variable name is defined in Domo under Admin -> Deomo Everywhere -> Embed -> Mapping KEY_ATTRIBUTE = keyAttributeName - # The MAPPING_VALUE is defined for each instance. Verify the value in the MAPPING_VALUE variable below matches the associated name in the "Attibute Value" colummn for the target organization at Admin -> Domo Everywhere -> Embed -> Mapping + # The MAPPING_VALUE is defined for each instance. Verify the value in the MAPPING_VALUE variable below matches the associated name in the "Attribute Value" column for the target organization at Admin -> Domo Everywhere -> Embed -> Mapping MAPPING_VALUE = XXXXXXXXXXXXXX ``` From afe07a01c0d529246f1425bbe896235b6139436e Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 11:40:32 -0600 Subject: [PATCH 04/22] docs: Listify code explanation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The markup looks like they intended a list—now it IS a list. This will help make things more readable. --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 988f1b0..a799258 100644 --- a/README.md +++ b/README.md @@ -56,17 +56,17 @@ MAPPING_VALUE = XXXXXXXXXXXXXX ``` - The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. - For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. - The EMBED_ID references the card or the dashboard you are embedding. - The EMBED_TYPE must be either the word 'dashboard' or 'card' (without the quotes). - Include the USE_XHR setting only if cookie based authentication won't work for the endpoint you create on your server. - If REPLACE_IFRAME is set to true, when a part of a card chart is clicked, it will cause the iframe to be replaced with a message showing the filter object the click generated otherwise the filters will just be reported via browser console messages. - You can include multiple embedded cards or dashboards on the sample dashboard as well by configuring more than one EMBEDID in your .env file (e.g. EMBED_ID2, EMBED_ID3). If you add these, you will need to uncomment their corresponding html in the sample.html file however for this to work and you may want to adjust the specified widths and heights of the embedded content again by modifying the sample.html file. - The IDP_URL is the Embed URL for Identity Broker is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing - The JWT_SECRET is the authentication method for authenticating to the IDP. This value should be kept safe. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing -> Change Authentication Method to JWT Secret, then click "Generate Secret" - The KEY_ATTRIBUTE is the variable name that you pass to denote which user gets routed to which instance. The name is customizable, so this variable name must match the value that is defined in Domo. Very by looking in Admin -> Domo Everywhre -> Embed -> Mapping and seeing the value in the "Key Attribute" section. The defined value in this variable must match what is listed in Domo. - The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. + - The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. + - For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. + - The EMBED_ID references the card or the dashboard you are embedding. + - The EMBED_TYPE must be either the word 'dashboard' or 'card' (without the quotes). + - Include the USE_XHR setting only if cookie based authentication won't work for the endpoint you create on your server. + - If REPLACE_IFRAME is set to true, when a part of a card chart is clicked, it will cause the iframe to be replaced with a message showing the filter object the click generated otherwise the filters will just be reported via browser console messages. + - You can include multiple embedded cards or dashboards on the sample dashboard as well by configuring more than one EMBEDID in your .env file (e.g. EMBED_ID2, EMBED_ID3). If you add these, you will need to uncomment their corresponding html in the sample.html file however for this to work and you may want to adjust the specified widths and heights of the embedded content again by modifying the sample.html file. + - The IDP_URL is the Embed URL for Identity Broker is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing + - The JWT_SECRET is the authentication method for authenticating to the IDP. This value should be kept safe. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing -> Change Authentication Method to JWT Secret, then click "Generate Secret" + - The KEY_ATTRIBUTE is the variable name that you pass to denote which user gets routed to which instance. The name is customizable, so this variable name must match the value that is defined in Domo. Very by looking in Admin -> Domo Everywhre -> Embed -> Mapping and seeing the value in the "Key Attribute" section. The defined value in this variable must match what is listed in Domo. + - The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. 8. Start the express server like this in the base folder of the project From 0c8f6c1bde45bc3f2ed366cb4040d69bf24ab3dc Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 11:50:22 -0600 Subject: [PATCH 05/22] docs: Inline help comments These comments are important enough to be included right next to what they describe, especially for people who aren't as familiar with these concepts as Domo engineers are. --- README.md | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index a799258..ad50dc9 100644 --- a/README.md +++ b/README.md @@ -35,39 +35,42 @@ 7. Inside of this file change the following configuration settings but using your own values: ```properties + # The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. + # For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. CLIENT_ID=YOUR_CLIENT_ID CLIENT_SECRET=YOUR_CLIENT_SECRET + + # The EMBED_ID references the card or the dashboard you are embedding. EMBED_ID=YOUR_EMBED_ID + + # The EMBED_TYPE must be either the word 'dashboard' or 'card' (without quotes). EMBED_TYPE=dashboard - # Optional settings + # Optional Settings + # ----------------- + # Include the USE_XHR setting only if cookie based authentication won't work for the endpoint you create on your server. USE_XHR=true + + # If REPLACE_IFRAME is set to true, when a part of a card chart is clicked, it will cause the iframe to be replaced with a message showing the filter object the click generated otherwise the filters will just be reported via browser console messages. REPLACE_IFRAME=true + + # You can include multiple embedded cards or dashboards on the sample dashboard as well by configuring more than one EMBEDID in your .env file (e.g. EMBED_ID2, EMBED_ID3). If you add these, you will need to uncomment their corresponding html in the sample.html file however for this to work and you may want to adjust the specified widths and heights of the embedded content again by modifying the sample.html file. EMBED_ID{X}=YOUR_EMBED_ID # Optional settings for testing the Domo Everywhere edit experience; routing users to specific instances. For more information on the Edit experience, see here: https://domo-support.domo.com/s/article/6523741250455?language=en_US # --- - # The Embed URL for Identity Broker is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing + # The IDP_URL is the Embed URL for Identity Broker, which is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing IDP_URL=HTTPS://YOUR_IDP_URL.domo.com + + # The JWT_SECRET is the authentication method for authenticating to the IDP. This value should be kept safe. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing -> Change Authentication Method to JWT Secret, then click "Generate Secret" JWT_SECRET = YOUR_JWT_SECRET - # The KEY_ATTRIBUTE variable name is defined in Domo under Admin -> Deomo Everywhere -> Embed -> Mapping + + # The KEY_ATTRIBUTE is the variable name that you pass to denote which user gets routed to which instance. The name is customizable, so this variable name must match the value that is defined in Domo. Verify by looking in Admin -> Domo Everywhre -> Embed -> Mapping and seeing the value in the "Key Attribute" section. The defined value in this variable must match what is listed in Domo. KEY_ATTRIBUTE = keyAttributeName - # The MAPPING_VALUE is defined for each instance. Verify the value in the MAPPING_VALUE variable below matches the associated name in the "Attribute Value" column for the target organization at Admin -> Domo Everywhere -> Embed -> Mapping + + # The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. MAPPING_VALUE = XXXXXXXXXXXXXX ``` - - - The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. - - For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. - - The EMBED_ID references the card or the dashboard you are embedding. - - The EMBED_TYPE must be either the word 'dashboard' or 'card' (without the quotes). - - Include the USE_XHR setting only if cookie based authentication won't work for the endpoint you create on your server. - - If REPLACE_IFRAME is set to true, when a part of a card chart is clicked, it will cause the iframe to be replaced with a message showing the filter object the click generated otherwise the filters will just be reported via browser console messages. - - You can include multiple embedded cards or dashboards on the sample dashboard as well by configuring more than one EMBEDID in your .env file (e.g. EMBED_ID2, EMBED_ID3). If you add these, you will need to uncomment their corresponding html in the sample.html file however for this to work and you may want to adjust the specified widths and heights of the embedded content again by modifying the sample.html file. - - The IDP_URL is the Embed URL for Identity Broker is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing - - The JWT_SECRET is the authentication method for authenticating to the IDP. This value should be kept safe. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing -> Change Authentication Method to JWT Secret, then click "Generate Secret" - - The KEY_ATTRIBUTE is the variable name that you pass to denote which user gets routed to which instance. The name is customizable, so this variable name must match the value that is defined in Domo. Very by looking in Admin -> Domo Everywhre -> Embed -> Mapping and seeing the value in the "Key Attribute" section. The defined value in this variable must match what is listed in Domo. - - The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. - 8. Start the express server like this in the base folder of the project ``` From f2e56c4108c98ffb1f3e4a74180310c0e1bf153c Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 11:52:18 -0600 Subject: [PATCH 06/22] docs: Comment out optional settings That way they're there if needed, but won't be unexpectedly changing things --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ad50dc9..dad235e 100644 --- a/README.md +++ b/README.md @@ -49,27 +49,27 @@ # Optional Settings # ----------------- # Include the USE_XHR setting only if cookie based authentication won't work for the endpoint you create on your server. - USE_XHR=true + #USE_XHR=true # If REPLACE_IFRAME is set to true, when a part of a card chart is clicked, it will cause the iframe to be replaced with a message showing the filter object the click generated otherwise the filters will just be reported via browser console messages. - REPLACE_IFRAME=true + #REPLACE_IFRAME=true # You can include multiple embedded cards or dashboards on the sample dashboard as well by configuring more than one EMBEDID in your .env file (e.g. EMBED_ID2, EMBED_ID3). If you add these, you will need to uncomment their corresponding html in the sample.html file however for this to work and you may want to adjust the specified widths and heights of the embedded content again by modifying the sample.html file. - EMBED_ID{X}=YOUR_EMBED_ID + #EMBED_ID{X}=YOUR_EMBED_ID # Optional settings for testing the Domo Everywhere edit experience; routing users to specific instances. For more information on the Edit experience, see here: https://domo-support.domo.com/s/article/6523741250455?language=en_US # --- # The IDP_URL is the Embed URL for Identity Broker, which is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing - IDP_URL=HTTPS://YOUR_IDP_URL.domo.com + #IDP_URL=HTTPS://YOUR_IDP_URL.domo.com # The JWT_SECRET is the authentication method for authenticating to the IDP. This value should be kept safe. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing -> Change Authentication Method to JWT Secret, then click "Generate Secret" - JWT_SECRET = YOUR_JWT_SECRET + #JWT_SECRET = YOUR_JWT_SECRET # The KEY_ATTRIBUTE is the variable name that you pass to denote which user gets routed to which instance. The name is customizable, so this variable name must match the value that is defined in Domo. Verify by looking in Admin -> Domo Everywhre -> Embed -> Mapping and seeing the value in the "Key Attribute" section. The defined value in this variable must match what is listed in Domo. - KEY_ATTRIBUTE = keyAttributeName + #KEY_ATTRIBUTE = keyAttributeName # The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. - MAPPING_VALUE = XXXXXXXXXXXXXX + #MAPPING_VALUE = XXXXXXXXXXXXXX ``` 8. Start the express server like this in the base folder of the project From 76befe6683503d9c5209b8d4e4150464915bd325 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:19:29 -0600 Subject: [PATCH 07/22] docs: Clarify what EMBED_ID looks like and where to find it --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dad235e..9e0fe3f 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ CLIENT_ID=YOUR_CLIENT_ID CLIENT_SECRET=YOUR_CLIENT_SECRET - # The EMBED_ID references the card or the dashboard you are embedding. + # The EMBED_ID references the card or the dashboard you are embedding; it will be some alphanumeric identifier like `K2Okl`. Get it from the embedding dialog box. EMBED_ID=YOUR_EMBED_ID # The EMBED_TYPE must be either the word 'dashboard' or 'card' (without quotes). From ad55b414470fc88d99587dea1ca4fc8ac6979be2 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:22:48 -0600 Subject: [PATCH 08/22] docs: Unnumber steps to avoid confusion and subify a substep --- README.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 9e0fe3f..03fe49c 100644 --- a/README.md +++ b/README.md @@ -18,22 +18,22 @@ 1. Install Node (https://nodejs.org/en/download/) -2. Install yarn (https://yarnpkg.com/en/docs/install) +1. Install yarn (https://yarnpkg.com/en/docs/install) -2. Locate or create the dashboard or card that you would like to embed in Domo. +1. Locate or create the dashboard or card that you would like to embed in Domo. -3. Embed the card or dashboard using the 'Private' Embed option. +1. Embed the card or dashboard using the 'Private' Embed option. -4. Clone or download this repository. +1. Clone or download this repository. -5. In the base folder of the repository run yarn to install the necessary dependencies. +1. In the base folder of the repository run yarn to install the necessary dependencies. ``` yarn ``` -6. Modify the existing file in the base folder of the project named `.env` +1. Modify the existing file in the base folder of the project named `.env` -7. Inside of this file change the following configuration settings but using your own values: +1. Inside of this file change the following configuration settings but using your own values: ```properties # The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. # For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. @@ -72,19 +72,20 @@ #MAPPING_VALUE = XXXXXXXXXXXXXX ``` -8. Start the express server like this in the base folder of the project +1. Start the express server like this in the base folder of the project ``` # yarn start ``` -9. An alternate port can be specified to start the program on by adding -p number to the end of the yarn start command like this: -``` -# yarn start -p 3002 -``` + - An alternate port can be specified to start the program on by adding -p number to the end of the yarn start command like this: + + ``` + # yarn start -p 3002 + ``` -9. In your browser go to the url localhost:3001 and verify that you are able to see you the card or dashboard appearing there after you login. The available usernames to login with are listed in the express.js file and they are as follows: mike, susan, tom, rachael, and samantha. Logging in as mike, susan, tom, or rachel will show the embedded card or dashboard as defined in the .env file. Logging in as samantha will display a full embedded Domo instance, as defined in the .env file. The password is not verified and so any will work. +1. In your browser go to the url localhost:3001 and verify that you are able to see you the card or dashboard appearing there after you login. The available usernames to login with are listed in the express.js file and they are as follows: mike, susan, tom, rachael, and samantha. Logging in as mike, susan, tom, or rachel will show the embedded card or dashboard as defined in the .env file. Logging in as samantha will display a full embedded Domo instance, as defined in the .env file. The password is not verified and so any will work. -10. Once you have verified your card or dashboard is showing up in the example site, open up the file users.js in a text editor and modify the filter settings for each user to customize the filtering that each user will have applied to them. Currently each user has an empty filter being applied to them "[]". There are some example filters in the file that are commented out that you can use that give you an idea of the format expected for the filters. Once you make filter changes to the users.js file, you will need to save the file, restart the express server, refresh the page, and then log back in to see your filter changes. The complete list of available operators for use in filters are as follows: "IN", "NOT_IN", "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREAT_THAN_EQUALS_TO", "LESS_THAN", "LESS_THAN_EQUALS_TO". Alternatively, modify the MAPPING_VALUE that is defined to route samantha to a different Organization when that user logs in. +1. Once you have verified your card or dashboard is showing up in the example site, open up the file users.js in a text editor and modify the filter settings for each user to customize the filtering that each user will have applied to them. Currently each user has an empty filter being applied to them "[]". There are some example filters in the file that are commented out that you can use that give you an idea of the format expected for the filters. Once you make filter changes to the users.js file, you will need to save the file, restart the express server, refresh the page, and then log back in to see your filter changes. The complete list of available operators for use in filters are as follows: "IN", "NOT_IN", "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREAT_THAN_EQUALS_TO", "LESS_THAN", "LESS_THAN_EQUALS_TO". Alternatively, modify the MAPPING_VALUE that is defined to route samantha to a different Organization when that user logs in. -11. For information on how the javascript api works to both send and receive messages from Domo embedded iframes see the jsapi.js file. To test out the api you can apply a filter to all of the cards by using the forms at the top of the page. You can also click on the charts and see how the code in the jsapi.js file uses procedure calls sent from the iframe to route the iframe to a different url including the filters as part of the new url. +1. For information on how the javascript api works to both send and receive messages from Domo embedded iframes see the jsapi.js file. To test out the api you can apply a filter to all of the cards by using the forms at the top of the page. You can also click on the charts and see how the code in the jsapi.js file uses procedure calls sent from the iframe to route the iframe to a different url including the filters as part of the new url. From 7fa45de117e09ce50239260f5744057146bd242d Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:28:44 -0600 Subject: [PATCH 09/22] docs: Abstract step and listify Instead of a giant wall of text, let's advise the user of what we're about to do --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 03fe49c..5b8ab11 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,11 @@ # yarn start -p 3002 ``` -1. In your browser go to the url localhost:3001 and verify that you are able to see you the card or dashboard appearing there after you login. The available usernames to login with are listed in the express.js file and they are as follows: mike, susan, tom, rachael, and samantha. Logging in as mike, susan, tom, or rachel will show the embedded card or dashboard as defined in the .env file. Logging in as samantha will display a full embedded Domo instance, as defined in the .env file. The password is not verified and so any will work. +1. Open App & Verify Embed + - In your browser go to the url localhost:3001 and verify that you are able to see you the card or dashboard appearing there after you login. + - The available usernames to login with are listed in the express.js file and they are as follows: mike, susan, tom, rachael, and samantha. + - Logging in as mike, susan, tom, or rachel will show the embedded card or dashboard as defined in the .env file. + - Logging in as **samantha** will display a **full** embedded Domo **instance**, as defined in the .env file. The password is not verified and so any will work. 1. Once you have verified your card or dashboard is showing up in the example site, open up the file users.js in a text editor and modify the filter settings for each user to customize the filtering that each user will have applied to them. Currently each user has an empty filter being applied to them "[]". There are some example filters in the file that are commented out that you can use that give you an idea of the format expected for the filters. Once you make filter changes to the users.js file, you will need to save the file, restart the express server, refresh the page, and then log back in to see your filter changes. The complete list of available operators for use in filters are as follows: "IN", "NOT_IN", "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREAT_THAN_EQUALS_TO", "LESS_THAN", "LESS_THAN_EQUALS_TO". Alternatively, modify the MAPPING_VALUE that is defined to route samantha to a different Organization when that user logs in. From 87381f45e3a0c0a263ec841aca32bbc683adf668 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:31:18 -0600 Subject: [PATCH 10/22] docs: Add important admonition about scopes --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 5b8ab11..f469ced 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,13 @@ 1. Modify the existing file in the base folder of the project named `.env` 1. Inside of this file change the following configuration settings but using your own values: + > [!IMPORTANT] + > For this specific app, when setting up your client id and secret, be sure to give your app at least the following **scopes**: + > - audit + > - data + > - dashboard + > - user + ```properties # The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. # For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. From 2e3525295225feecbfa3b954541c0c672c0ceecb Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:43:32 -0600 Subject: [PATCH 11/22] docs: Re-order important info first --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f469ced..58848c1 100644 --- a/README.md +++ b/README.md @@ -93,8 +93,9 @@ 1. Open App & Verify Embed - In your browser go to the url localhost:3001 and verify that you are able to see you the card or dashboard appearing there after you login. - The available usernames to login with are listed in the express.js file and they are as follows: mike, susan, tom, rachael, and samantha. + - The password is not verified and so any will work. - Logging in as mike, susan, tom, or rachel will show the embedded card or dashboard as defined in the .env file. - - Logging in as **samantha** will display a **full** embedded Domo **instance**, as defined in the .env file. The password is not verified and so any will work. + - Logging in as **samantha** will display a **full** embedded Domo **instance**, as defined in the .env file. 1. Once you have verified your card or dashboard is showing up in the example site, open up the file users.js in a text editor and modify the filter settings for each user to customize the filtering that each user will have applied to them. Currently each user has an empty filter being applied to them "[]". There are some example filters in the file that are commented out that you can use that give you an idea of the format expected for the filters. Once you make filter changes to the users.js file, you will need to save the file, restart the express server, refresh the page, and then log back in to see your filter changes. The complete list of available operators for use in filters are as follows: "IN", "NOT_IN", "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREAT_THAN_EQUALS_TO", "LESS_THAN", "LESS_THAN_EQUALS_TO". Alternatively, modify the MAPPING_VALUE that is defined to route samantha to a different Organization when that user logs in. From 6e3ff79abe9b62bfef2617c43d4f709efe5b6f62 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:48:31 -0600 Subject: [PATCH 12/22] docs: Give step some hierarchy for clarity --- README.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 58848c1..bb2511d 100644 --- a/README.md +++ b/README.md @@ -91,11 +91,15 @@ ``` 1. Open App & Verify Embed - - In your browser go to the url localhost:3001 and verify that you are able to see you the card or dashboard appearing there after you login. - - The available usernames to login with are listed in the express.js file and they are as follows: mike, susan, tom, rachael, and samantha. - - The password is not verified and so any will work. - - Logging in as mike, susan, tom, or rachel will show the embedded card or dashboard as defined in the .env file. - - Logging in as **samantha** will display a **full** embedded Domo **instance**, as defined in the .env file. + 1. **Open App** + - In your browser go to the url localhost:3001 and verify that you are able to see you the card or dashboard appearing there after you login. + 1. **Login** + - The available usernames to login with are listed in the express.js file and they are as follows: mike, susan, tom, rachael, and samantha. + - The password is not verified and so any will work. + - Logging in as mike, susan, tom, or rachel will show the embedded card or dashboard as defined in the .env file. + - Logging in as **samantha** will display a **full** embedded Domo **instance**, as defined in the .env file. + 1. **Verify** + - Once logged in, your card/dashboard should appear embedded on the page. 1. Once you have verified your card or dashboard is showing up in the example site, open up the file users.js in a text editor and modify the filter settings for each user to customize the filtering that each user will have applied to them. Currently each user has an empty filter being applied to them "[]". There are some example filters in the file that are commented out that you can use that give you an idea of the format expected for the filters. Once you make filter changes to the users.js file, you will need to save the file, restart the express server, refresh the page, and then log back in to see your filter changes. The complete list of available operators for use in filters are as follows: "IN", "NOT_IN", "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREAT_THAN_EQUALS_TO", "LESS_THAN", "LESS_THAN_EQUALS_TO". Alternatively, modify the MAPPING_VALUE that is defined to route samantha to a different Organization when that user logs in. From aed54397f8e7495ce4348b954a9822c066dd87e1 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:56:14 -0600 Subject: [PATCH 13/22] docs: Go back to explicit numbering to avoid reset Unfortunately, the admonition makes the step number reset. Using explicit numbers fixes this. --- README.md | 113 +++++++++++++++++++++++++++--------------------------- 1 file changed, 56 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index bb2511d..820a31c 100644 --- a/README.md +++ b/README.md @@ -18,68 +18,67 @@ 1. Install Node (https://nodejs.org/en/download/) -1. Install yarn (https://yarnpkg.com/en/docs/install) +2. Install yarn (https://yarnpkg.com/en/docs/install) -1. Locate or create the dashboard or card that you would like to embed in Domo. +3. Locate or create the dashboard or card that you would like to embed in Domo. -1. Embed the card or dashboard using the 'Private' Embed option. +4. Embed the card or dashboard using the 'Private' Embed option. -1. Clone or download this repository. +5. Clone or download this repository. -1. In the base folder of the repository run yarn to install the necessary dependencies. +6. In the base folder of the repository run yarn to install the necessary dependencies. ``` yarn ``` -1. Modify the existing file in the base folder of the project named `.env` - -1. Inside of this file change the following configuration settings but using your own values: - > [!IMPORTANT] - > For this specific app, when setting up your client id and secret, be sure to give your app at least the following **scopes**: - > - audit - > - data - > - dashboard - > - user - - ```properties - # The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. - # For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. - CLIENT_ID=YOUR_CLIENT_ID - CLIENT_SECRET=YOUR_CLIENT_SECRET - - # The EMBED_ID references the card or the dashboard you are embedding; it will be some alphanumeric identifier like `K2Okl`. Get it from the embedding dialog box. - EMBED_ID=YOUR_EMBED_ID - - # The EMBED_TYPE must be either the word 'dashboard' or 'card' (without quotes). - EMBED_TYPE=dashboard - - # Optional Settings - # ----------------- - # Include the USE_XHR setting only if cookie based authentication won't work for the endpoint you create on your server. - #USE_XHR=true - - # If REPLACE_IFRAME is set to true, when a part of a card chart is clicked, it will cause the iframe to be replaced with a message showing the filter object the click generated otherwise the filters will just be reported via browser console messages. - #REPLACE_IFRAME=true - - # You can include multiple embedded cards or dashboards on the sample dashboard as well by configuring more than one EMBEDID in your .env file (e.g. EMBED_ID2, EMBED_ID3). If you add these, you will need to uncomment their corresponding html in the sample.html file however for this to work and you may want to adjust the specified widths and heights of the embedded content again by modifying the sample.html file. - #EMBED_ID{X}=YOUR_EMBED_ID - - # Optional settings for testing the Domo Everywhere edit experience; routing users to specific instances. For more information on the Edit experience, see here: https://domo-support.domo.com/s/article/6523741250455?language=en_US - # --- - # The IDP_URL is the Embed URL for Identity Broker, which is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing - #IDP_URL=HTTPS://YOUR_IDP_URL.domo.com - - # The JWT_SECRET is the authentication method for authenticating to the IDP. This value should be kept safe. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing -> Change Authentication Method to JWT Secret, then click "Generate Secret" - #JWT_SECRET = YOUR_JWT_SECRET - - # The KEY_ATTRIBUTE is the variable name that you pass to denote which user gets routed to which instance. The name is customizable, so this variable name must match the value that is defined in Domo. Verify by looking in Admin -> Domo Everywhre -> Embed -> Mapping and seeing the value in the "Key Attribute" section. The defined value in this variable must match what is listed in Domo. - #KEY_ATTRIBUTE = keyAttributeName - - # The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. - #MAPPING_VALUE = XXXXXXXXXXXXXX - ``` - -1. Start the express server like this in the base folder of the project +7. Modify the existing file in the base folder of the project named `.env` + +8. Inside of this file change the following configuration settings but using your own values: + > [!IMPORTANT] + > For this specific app, when setting up your client id and secret, be sure to give your app at least the following **scopes**: + > - audit + > - data + > - dashboard + > - user + + ```properties + # The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. + # For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. + CLIENT_ID=YOUR_CLIENT_ID + CLIENT_SECRET=YOUR_CLIENT_SECRET + + # The EMBED_ID references the card or the dashboard you are embedding; it will be some alphanumeric identifier like `K2Okl`. Get it from the embedding dialog box. + EMBED_ID=YOUR_EMBED_ID + + # The EMBED_TYPE must be either the word 'dashboard' or 'card' (without quotes). + EMBED_TYPE=dashboard + + # Optional Settings + # ----------------- + # Include the USE_XHR setting only if cookie based authentication won't work for the endpoint you create on your server. + #USE_XHR=true + + # If REPLACE_IFRAME is set to true, when a part of a card chart is clicked, it will cause the iframe to be replaced with a message showing the filter object the click generated otherwise the filters will just be reported via browser console messages. + #REPLACE_IFRAME=true + + # You can include multiple embedded cards or dashboards on the sample dashboard as well by configuring more than one EMBEDID in your .env file (e.g. EMBED_ID2, EMBED_ID3). If you add these, you will need to uncomment their corresponding html in the sample.html file however for this to work and you may want to adjust the specified widths and heights of the embedded content again by modifying the sample.html file. + #EMBED_ID{X}=YOUR_EMBED_ID + + # Optional settings for testing the Domo Everywhere edit experience; routing users to specific instances. For more information on the Edit experience, see here: https://domo-support.domo.com/s/article/6523741250455?language=en_US + # --- + # The IDP_URL is the Embed URL for Identity Broker, which is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing + #IDP_URL=HTTPS://YOUR_IDP_URL.domo.com + + # The JWT_SECRET is the authentication method for authenticating to the IDP. This value should be kept safe. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing -> Change Authentication Method to JWT Secret, then click "Generate Secret" + #JWT_SECRET = YOUR_JWT_SECRET + + # The KEY_ATTRIBUTE is the variable name that you pass to denote which user gets routed to which instance. The name is customizable, so this variable name must match the value that is defined in Domo. Verify by looking in Admin -> Domo Everywhre -> Embed -> Mapping and seeing the value in the "Key Attribute" section. The defined value in this variable must match what is listed in Domo. + #KEY_ATTRIBUTE = keyAttributeName + + # The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. + #MAPPING_VALUE = XXXXXXXXXXXXXX + ``` +9. Start the express server like this in the base folder of the project ``` # yarn start ``` @@ -90,7 +89,7 @@ # yarn start -p 3002 ``` -1. Open App & Verify Embed +10. Open App & Verify Embed 1. **Open App** - In your browser go to the url localhost:3001 and verify that you are able to see you the card or dashboard appearing there after you login. 1. **Login** @@ -102,6 +101,6 @@ - Once logged in, your card/dashboard should appear embedded on the page. -1. Once you have verified your card or dashboard is showing up in the example site, open up the file users.js in a text editor and modify the filter settings for each user to customize the filtering that each user will have applied to them. Currently each user has an empty filter being applied to them "[]". There are some example filters in the file that are commented out that you can use that give you an idea of the format expected for the filters. Once you make filter changes to the users.js file, you will need to save the file, restart the express server, refresh the page, and then log back in to see your filter changes. The complete list of available operators for use in filters are as follows: "IN", "NOT_IN", "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREAT_THAN_EQUALS_TO", "LESS_THAN", "LESS_THAN_EQUALS_TO". Alternatively, modify the MAPPING_VALUE that is defined to route samantha to a different Organization when that user logs in. +11. Once you have verified your card or dashboard is showing up in the example site, open up the file users.js in a text editor and modify the filter settings for each user to customize the filtering that each user will have applied to them. Currently each user has an empty filter being applied to them "[]". There are some example filters in the file that are commented out that you can use that give you an idea of the format expected for the filters. Once you make filter changes to the users.js file, you will need to save the file, restart the express server, refresh the page, and then log back in to see your filter changes. The complete list of available operators for use in filters are as follows: "IN", "NOT_IN", "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREAT_THAN_EQUALS_TO", "LESS_THAN", "LESS_THAN_EQUALS_TO". Alternatively, modify the MAPPING_VALUE that is defined to route samantha to a different Organization when that user logs in. -1. For information on how the javascript api works to both send and receive messages from Domo embedded iframes see the jsapi.js file. To test out the api you can apply a filter to all of the cards by using the forms at the top of the page. You can also click on the charts and see how the code in the jsapi.js file uses procedure calls sent from the iframe to route the iframe to a different url including the filters as part of the new url. +12. For information on how the javascript api works to both send and receive messages from Domo embedded iframes see the jsapi.js file. To test out the api you can apply a filter to all of the cards by using the forms at the top of the page. You can also click on the charts and see how the code in the jsapi.js file uses procedure calls sent from the iframe to route the iframe to a different url including the filters as part of the new url. From 382eb2d40915410ee7604c6cbe840c62f9f031be Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:56:58 -0600 Subject: [PATCH 14/22] docs: Fix .env formatting It was in one level too deep, breaking the formatting --- README.md | 74 +++++++++++++++++++++++++++---------------------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 820a31c..1ac6ddc 100644 --- a/README.md +++ b/README.md @@ -41,43 +41,43 @@ > - dashboard > - user - ```properties - # The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. - # For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. - CLIENT_ID=YOUR_CLIENT_ID - CLIENT_SECRET=YOUR_CLIENT_SECRET - - # The EMBED_ID references the card or the dashboard you are embedding; it will be some alphanumeric identifier like `K2Okl`. Get it from the embedding dialog box. - EMBED_ID=YOUR_EMBED_ID - - # The EMBED_TYPE must be either the word 'dashboard' or 'card' (without quotes). - EMBED_TYPE=dashboard - - # Optional Settings - # ----------------- - # Include the USE_XHR setting only if cookie based authentication won't work for the endpoint you create on your server. - #USE_XHR=true - - # If REPLACE_IFRAME is set to true, when a part of a card chart is clicked, it will cause the iframe to be replaced with a message showing the filter object the click generated otherwise the filters will just be reported via browser console messages. - #REPLACE_IFRAME=true - - # You can include multiple embedded cards or dashboards on the sample dashboard as well by configuring more than one EMBEDID in your .env file (e.g. EMBED_ID2, EMBED_ID3). If you add these, you will need to uncomment their corresponding html in the sample.html file however for this to work and you may want to adjust the specified widths and heights of the embedded content again by modifying the sample.html file. - #EMBED_ID{X}=YOUR_EMBED_ID - - # Optional settings for testing the Domo Everywhere edit experience; routing users to specific instances. For more information on the Edit experience, see here: https://domo-support.domo.com/s/article/6523741250455?language=en_US - # --- - # The IDP_URL is the Embed URL for Identity Broker, which is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing - #IDP_URL=HTTPS://YOUR_IDP_URL.domo.com - - # The JWT_SECRET is the authentication method for authenticating to the IDP. This value should be kept safe. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing -> Change Authentication Method to JWT Secret, then click "Generate Secret" - #JWT_SECRET = YOUR_JWT_SECRET - - # The KEY_ATTRIBUTE is the variable name that you pass to denote which user gets routed to which instance. The name is customizable, so this variable name must match the value that is defined in Domo. Verify by looking in Admin -> Domo Everywhre -> Embed -> Mapping and seeing the value in the "Key Attribute" section. The defined value in this variable must match what is listed in Domo. - #KEY_ATTRIBUTE = keyAttributeName - - # The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. - #MAPPING_VALUE = XXXXXXXXXXXXXX - ``` + ```properties + # The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. + # For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. + CLIENT_ID=YOUR_CLIENT_ID + CLIENT_SECRET=YOUR_CLIENT_SECRET + + # The EMBED_ID references the card or the dashboard you are embedding; it will be some alphanumeric identifier like `K2Okl`. Get it from the embedding dialog box. + EMBED_ID=YOUR_EMBED_ID + + # The EMBED_TYPE must be either the word 'dashboard' or 'card' (without quotes). + EMBED_TYPE=dashboard + + # Optional Settings + # ----------------- + # Include the USE_XHR setting only if cookie based authentication won't work for the endpoint you create on your server. + #USE_XHR=true + + # If REPLACE_IFRAME is set to true, when a part of a card chart is clicked, it will cause the iframe to be replaced with a message showing the filter object the click generated otherwise the filters will just be reported via browser console messages. + #REPLACE_IFRAME=true + + # You can include multiple embedded cards or dashboards on the sample dashboard as well by configuring more than one EMBEDID in your .env file (e.g. EMBED_ID2, EMBED_ID3). If you add these, you will need to uncomment their corresponding html in the sample.html file however for this to work and you may want to adjust the specified widths and heights of the embedded content again by modifying the sample.html file. + #EMBED_ID{X}=YOUR_EMBED_ID + + # Optional settings for testing the Domo Everywhere edit experience; routing users to specific instances. For more information on the Edit experience, see here: https://domo-support.domo.com/s/article/6523741250455?language=en_US + # --- + # The IDP_URL is the Embed URL for Identity Broker, which is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing + #IDP_URL=HTTPS://YOUR_IDP_URL.domo.com + + # The JWT_SECRET is the authentication method for authenticating to the IDP. This value should be kept safe. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing -> Change Authentication Method to JWT Secret, then click "Generate Secret" + #JWT_SECRET = YOUR_JWT_SECRET + + # The KEY_ATTRIBUTE is the variable name that you pass to denote which user gets routed to which instance. The name is customizable, so this variable name must match the value that is defined in Domo. Verify by looking in Admin -> Domo Everywhre -> Embed -> Mapping and seeing the value in the "Key Attribute" section. The defined value in this variable must match what is listed in Domo. + #KEY_ATTRIBUTE = keyAttributeName + + # The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. + #MAPPING_VALUE = XXXXXXXXXXXXXX + ``` 9. Start the express server like this in the base folder of the project ``` # yarn start From f8eec8956d4aff9342190d68f29294885a7bedb2 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:57:51 -0600 Subject: [PATCH 15/22] docs: Remove comment from yarn commands This poses a risk of confusing or tripping up people. It seems better to omit it. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1ac6ddc..bc04fc8 100644 --- a/README.md +++ b/README.md @@ -80,13 +80,13 @@ ``` 9. Start the express server like this in the base folder of the project ``` - # yarn start + yarn start ``` - An alternate port can be specified to start the program on by adding -p number to the end of the yarn start command like this: ``` - # yarn start -p 3002 + yarn start -p 3002 ``` 10. Open App & Verify Embed From 0ab87bdf32ab64af3ea9600fe5c7654882b46c90 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:58:56 -0600 Subject: [PATCH 16/22] docs: Add backticks to URL --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bc04fc8..a765d7a 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,7 @@ 10. Open App & Verify Embed 1. **Open App** - - In your browser go to the url localhost:3001 and verify that you are able to see you the card or dashboard appearing there after you login. + - In your browser go to the url `localhost:3001` and verify that you are able to see you the card or dashboard appearing there after you login. 1. **Login** - The available usernames to login with are listed in the express.js file and they are as follows: mike, susan, tom, rachael, and samantha. - The password is not verified and so any will work. From 8bb6c061c9fc394686c1016aa4c5a48e7c93e209 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 12:59:59 -0600 Subject: [PATCH 17/22] docs: Remove repeated details --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a765d7a..b121f72 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,7 @@ 10. Open App & Verify Embed 1. **Open App** - - In your browser go to the url `localhost:3001` and verify that you are able to see you the card or dashboard appearing there after you login. + - In your browser go to the url `localhost:3001` 1. **Login** - The available usernames to login with are listed in the express.js file and they are as follows: mike, susan, tom, rachael, and samantha. - The password is not verified and so any will work. From d14c5824392f76e511a86a24da128cafd6fdc1f2 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 13:06:54 -0600 Subject: [PATCH 18/22] docs: Add warning about what you need defined for full instance embed to work --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b121f72..79f9a1d 100644 --- a/README.md +++ b/README.md @@ -95,8 +95,9 @@ 1. **Login** - The available usernames to login with are listed in the express.js file and they are as follows: mike, susan, tom, rachael, and samantha. - The password is not verified and so any will work. - - Logging in as mike, susan, tom, or rachel will show the embedded card or dashboard as defined in the .env file. - - Logging in as **samantha** will display a **full** embedded Domo **instance**, as defined in the .env file. + - Logging in as mike, susan, tom, or rachel will show the embedded card or dashboard as defined in the `.env` file. + - Logging in as **samantha** will display a **full** embedded Domo **instance**, as defined in the `.env` file. + - :exclamation: For full instance embed to work, you need to have provided, `JWT_SECRET`,`KEY_ATTRIBUTE`, and `MAPPING_VALUE` in your `.env` file. 1. **Verify** - Once logged in, your card/dashboard should appear embedded on the page. From 733cd9f658087bcf44195c5e9ea73337e67a0d8f Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 13:16:03 -0600 Subject: [PATCH 19/22] docs: Summarize and breakdown step This helps the user read and understand what we've written --- README.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 79f9a1d..289f854 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,20 @@ - Once logged in, your card/dashboard should appear embedded on the page. -11. Once you have verified your card or dashboard is showing up in the example site, open up the file users.js in a text editor and modify the filter settings for each user to customize the filtering that each user will have applied to them. Currently each user has an empty filter being applied to them "[]". There are some example filters in the file that are commented out that you can use that give you an idea of the format expected for the filters. Once you make filter changes to the users.js file, you will need to save the file, restart the express server, refresh the page, and then log back in to see your filter changes. The complete list of available operators for use in filters are as follows: "IN", "NOT_IN", "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREAT_THAN_EQUALS_TO", "LESS_THAN", "LESS_THAN_EQUALS_TO". Alternatively, modify the MAPPING_VALUE that is defined to route samantha to a different Organization when that user logs in. - -12. For information on how the javascript api works to both send and receive messages from Domo embedded iframes see the jsapi.js file. To test out the api you can apply a filter to all of the cards by using the forms at the top of the page. You can also click on the charts and see how the code in the jsapi.js file uses procedure calls sent from the iframe to route the iframe to a different url including the filters as part of the new url. +11. Try Customizing User-level Filtering + - Open up the `users.js` file in a text editor and modify the filter settings for each user to customize the filtering that each user will have applied to them. + - Currently each user has an empty filter, `[]`, being applied to them. + - There are some example filters in the file that are commented out that you can use that give you an idea of the format expected for the filters. + - Once you make filter changes to the `users.js` file, you will need to save the file, restart the express server, refresh the page, and then log back in to see your filter changes. + - The complete list of available operators for use in filters are as follows: + - "IN" + - "NOT_IN" + - "EQUALS" + - "NOT_EQUALS" + - "GREATER_THAN" + - "GREAT_THAN_EQUALS_TO" + - "LESS_THAN" + - "LESS_THAN_EQUALS_TO" + - Alternatively, modify the `MAPPING_VALUE` that is defined to route samantha to a different Organization when that user logs in. + +13. For information on how the javascript api works to both send and receive messages from Domo embedded iframes see the jsapi.js file. To test out the api you can apply a filter to all of the cards by using the forms at the top of the page. You can also click on the charts and see how the code in the jsapi.js file uses procedure calls sent from the iframe to route the iframe to a different url including the filters as part of the new url. From 521b3820d23e6c60b856346ba617f6dd60807ebf Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 13:31:17 -0600 Subject: [PATCH 20/22] docs: Break down last step --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 289f854..9a0991a 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,9 @@ - "GREAT_THAN_EQUALS_TO" - "LESS_THAN" - "LESS_THAN_EQUALS_TO" - - Alternatively, modify the `MAPPING_VALUE` that is defined to route samantha to a different Organization when that user logs in. + - You can also modify the `MAPPING_VALUE` that is defined to route samantha to a different Organization when that user logs in. -13. For information on how the javascript api works to both send and receive messages from Domo embedded iframes see the jsapi.js file. To test out the api you can apply a filter to all of the cards by using the forms at the top of the page. You can also click on the charts and see how the code in the jsapi.js file uses procedure calls sent from the iframe to route the iframe to a different url including the filters as part of the new url. +13. Learn More + - For information on how the JavaScript API works to both send and receive messages from Domo embedded iframes, see the `public/jsapi.js` file. + - To test out the API, you can apply a filter to all of the cards by using the forms at the top of the app page. + - You can also click on the charts and see how the code in the `jsapi.js` file uses procedure calls sent from the iframe to route the iframe to a different url including the filters as part of the new url. From e68fa2fd86d1b37b8e8bfa9deea4035e6ccaaffc Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 13:32:42 -0600 Subject: [PATCH 21/22] docs: Fix numbering of last step --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9a0991a..9fbdeda 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,7 @@ # The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. #MAPPING_VALUE = XXXXXXXXXXXXXX ``` + 9. Start the express server like this in the base folder of the project ``` yarn start @@ -118,7 +119,7 @@ - "LESS_THAN_EQUALS_TO" - You can also modify the `MAPPING_VALUE` that is defined to route samantha to a different Organization when that user logs in. -13. Learn More +12. Learn More - For information on how the JavaScript API works to both send and receive messages from Domo embedded iframes, see the `public/jsapi.js` file. - To test out the API, you can apply a filter to all of the cards by using the forms at the top of the app page. - You can also click on the charts and see how the code in the `jsapi.js` file uses procedure calls sent from the iframe to route the iframe to a different url including the filters as part of the new url. From 1d733e8623fdb53a588f358b31a5504b58bb25a3 Mon Sep 17 00:00:00 2001 From: Bradley Turek Date: Tue, 27 Aug 2024 15:34:40 -0600 Subject: [PATCH 22/22] fix: :lock: prevent secret leakage by not tracking `.env` by default Previously, it would've been easy for someone to accidentally commit their client id and secret. Now, we make that mistake much harder to make. --- .env | 6 ------ .env.template | 38 ++++++++++++++++++++++++++++++++++++++ .gitignore | 1 + README.md | 4 ++-- 4 files changed, 41 insertions(+), 8 deletions(-) delete mode 100644 .env create mode 100644 .env.template diff --git a/.env b/.env deleted file mode 100644 index 8666752..0000000 --- a/.env +++ /dev/null @@ -1,6 +0,0 @@ - -# Sample configuration: you will need to change this for yours to work -CLIENT_ID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -EMBED_ID=XXXXX -EMBED_TYPE=dashboard diff --git a/.env.template b/.env.template new file mode 100644 index 0000000..5f1c880 --- /dev/null +++ b/.env.template @@ -0,0 +1,38 @@ +# 👉 Rename this file from `.env.template` to `.env` for the app to pick up the configuration + +# Sample configuration: you will need to change this for yours to work +# The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed. +# For more information about creating the CLIENT_ID and CLIENT_SECRET see https://developer.domo.com/docs/authentication/overview-4. +CLIENT_ID=YOUR_CLIENT_ID +CLIENT_SECRET=YOUR_CLIENT_SECRET + +# The EMBED_ID references the card or the dashboard you are embedding; it will be some alphanumeric identifier like `K2Okl`. Get it from the embedding dialog box. +EMBED_ID=YOUR_EMBED_ID + +# The EMBED_TYPE must be either the word 'dashboard' or 'card' (without quotes). +EMBED_TYPE=dashboard + +# Optional Settings +# ----------------- +# Include the USE_XHR setting only if cookie based authentication won't work for the endpoint you create on your server. +#USE_XHR=true + +# If REPLACE_IFRAME is set to true, when a part of a card chart is clicked, it will cause the iframe to be replaced with a message showing the filter object the click generated otherwise the filters will just be reported via browser console messages. +#REPLACE_IFRAME=true + +# You can include multiple embedded cards or dashboards on the sample dashboard as well by configuring more than one EMBEDID in your .env file (e.g. EMBED_ID2, EMBED_ID3). If you add these, you will need to uncomment their corresponding html in the sample.html file however for this to work and you may want to adjust the specified widths and heights of the embedded content again by modifying the sample.html file. +#EMBED_ID{X}=YOUR_EMBED_ID + +# Optional settings for testing the Domo Everywhere edit experience; routing users to specific instances. For more information on the Edit experience, see here: https://domo-support.domo.com/s/article/6523741250455?language=en_US +# --- +# The IDP_URL is the Embed URL for Identity Broker, which is the URL that receives authentication, verifies the user, and routes to the correct place. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing +#IDP_URL=HTTPS://YOUR_IDP_URL.domo.com + +# The JWT_SECRET is the authentication method for authenticating to the IDP. This value should be kept safe. It is found in your primary Domo instance under Admin -> Domo Everywhere -> Embed -> Routing -> Change Authentication Method to JWT Secret, then click "Generate Secret" +#JWT_SECRET = YOUR_JWT_SECRET + +# The KEY_ATTRIBUTE is the variable name that you pass to denote which user gets routed to which instance. The name is customizable, so this variable name must match the value that is defined in Domo. Verify by looking in Admin -> Domo Everywhre -> Embed -> Mapping and seeing the value in the "Key Attribute" section. The defined value in this variable must match what is listed in Domo. +#KEY_ATTRIBUTE = keyAttributeName + +# The MAPPING_VALUE is the value used to route the authenticated user to the correct Domo isntance. It needs to match the defined value for your target instance as shown in Admin -> Domo Everywhere -> Embed -> Mapping next to the Organization domain you wish to route to, listed in the "Attribute Value" column. +#MAPPING_VALUE = XXXXXXXXXXXXXX \ No newline at end of file diff --git a/.gitignore b/.gitignore index c2658d7..713d500 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ node_modules/ +.env diff --git a/README.md b/README.md index 9fbdeda..0df8370 100644 --- a/README.md +++ b/README.md @@ -31,9 +31,9 @@ yarn ``` -7. Modify the existing file in the base folder of the project named `.env` +7. Rename the `.env.template` file to `.env` -8. Inside of this file change the following configuration settings but using your own values: +8. Inside of this file, change the following configuration settings but using your own values: > [!IMPORTANT] > For this specific app, when setting up your client id and secret, be sure to give your app at least the following **scopes**: > - audit