-
Notifications
You must be signed in to change notification settings - Fork 34
/
readme.txt
265 lines (189 loc) · 13.5 KB
/
readme.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
=== Power BI Embedded for WordPress ===
Contributors: atlaspolicy, upnrunn, stegel
Tags: powerbi-embedded, wordpress-plugin, powerbi, wordpress
Requires at least: 5.0.0
Requires PHP: 7.0
Tested up to: 6.2.2
Stable tag: 1.1.7
License: GNU General Public License v3.0
License URI: https://www.gnu.org/licenses/lgpl.html
This WordPress plugin supports Microsoft Power BI Embedded, including dashboards, reports, report visuals, Q&A, and tiles. It also supports filters and slicers passed in as a JSON object.
== Description ==
This WordPress plugin supports Microsoft Power BI Embedded, including dashboards, reports, report visuals, Q&A, and tiles. Power BI is a sophisticated data analytics software and service package from Microsoft. More information on Power BI is available at [www.powerbi.com](http://www.powerbi.com).
Contribute to this plugin on GitHub at [https://github.com/atlaspolicy/power-bi-embedded](https://github.com/atlaspolicy/power-bi-embedded)!
This plugin uses the Power BI REST API to access various types of content and easily embed them on a WordPress site using a shortcode. The plugin follows the "app owns data" process as documented by Microsoft at [https://docs.microsoft.com/en-us/power-bi/developer/embedding-content](https://docs.microsoft.com/en-us/power-bi/developer/embedding-content). See [https://docs.microsoft.com/en-us/power-bi/developer/embedding](https://docs.microsoft.com/en-us/power-bi/developer/embedding) for more information from Microsoft on how to Power BI embed content.
The plugin relies on Microsoft's JavaScript library for embedding Power BI available on Github here: [https://github.com/Microsoft/PowerBI-JavaScript](https://github.com/Microsoft/PowerBI-JavaScript).
In order to use this plugin, users must first register an app with Azure AD to embed Power BI content. See [https://docs.microsoft.com/en-us/power-bi/developer/register-app](https://docs.microsoft.com/en-us/power-bi/developer/register-app) for more information on how to register an app. Make sure to write down your Client ID and Client Secret when you register the app.
= Plugin Settings Page =
The "app owns data" process requires that a single, master Power BI Pro account controls access. The credentials for this account are configured one time on the plugin settings page. The plugin will authenticate against Azure AD with those stored credentials.
* User name: Email address for the Power BI Pro master account.
* Password: Password for the Power BI Pro master account.
* Client ID: The Client ID for the app you registered with Azure AD.
* Client Secret: The Client Secret for the app you registered with Azure AD.
After you save your changes, you'll see the authentication status on the settings page if it worked. Once you've configured the plugin, you can now add Power BI content to your WordPress site and embed it wherever you want.
The plugin also includes support to control the Power BI Embedded resource on Azure. This can be really helpful if you're trying to control costs by disabling the resource when it's not in use. The scheduling can be controlled on a daily basis by setting the hour to enable and the hour to disable the resource. If you don't need to disable the resource, then you can ignore this section.
* Tenant ID or Directory ID under Azure Active Directory for Office 365: The Directory ID is under the Properties section of the Azure Active Directory on the Azure portal.
* Subscription ID for Power BI Resource: Read directly from Azure portal.
* Resource Group Name: Read directly from the Azure portal.
* Resource Name: Read directly from the Azure portal.
* Sunday/Saturday: Set the time to start and pause the resource on a daily basis.
For scheduling, it is recommended to use cron on your web server instead of WP Cron. Many websites exist to walk you through the process of using your web server instead of WP Cron. For example, see [https://www.nextscripts.com/tutorials/wp-cron-scheduling-tasks-in-wordpress](https://www.nextscripts.com/tutorials/wp-cron-scheduling-tasks-in-wordpress).
= Power BI Content =
The plugin uses a custom content type for each Power BI component to embed (dashboard, report, etc.). Go to "All Power BI Items" to add a new component.
* Embed Type: Report, Report Visual, Q&A, Dashboard, Tile.
The Embed Type determines the remaining fields to fill out.
= Report =
* Report Mode: View, Edit, Create
* Report ID: Enter the unique identifier for the report. You can find the identifier by viewing a report in the Power BI Service. The identifier is in the URL.
* Group ID: Enter the unique identifier for the group. You can find the identifier by viewing a dashboard or report in the Power BI Service. The identifier is in the URL.
* Dataset ID: Enter the unique identifier for the dataset. You can find the identifier by viewing a dashboard in the Power BI Service. The identifier is in the URL. This is only needed for Create Mode.
= Report Visual =
* Report ID: Enter the unique identifier for the report. You can find the identifier by viewing a report in the Power BI Service. The identifier is in the URL.
* Group ID: Enter the unique identifier for the group. You can find the identifier by viewing a dashboard or report in the Power BI Service. The identifier is in the URL.
* Page Name: Enter the unique identifier for the Page. You can find the identifier by viewing the page within a report in the Power BI Service. The identifier is in the URL.
* Visual Name: The Visual Name can be retrieved using the GetVisuals method on the Page object.
= Q&A =
* Q&A Mode: Show Q&A, Show Q&A with predefined question, Show answer only with predefined question
* Q&A Input Question: Only necessary for "Show Q&A with predefined question" and "Show answer only with predefined question"
* Group ID: Enter the unique identifier for the group. You can find the identifier by viewing a dashboard or report in the Power BI Service. The identifier is in the URL.
* Dataset ID: Enter the unique identifier for the dataset. You can find the identifier by viewing a dashboard in the Power BI Service. The identifier is in the URL. This is only needed for Create Mode.
= Dashboard =
* Dashboard ID: Enter the unique identifier for the dashboard. You can find the identifier by viewing a dashboard in the Power BI Service. The identifier is in the URL.
* Group ID: Enter the unique identifier for the group. You can find the identifier by viewing a dashboard or report in the Power BI Service. The identifier is in the URL.
= Tile =
* Dashboard ID: Enter the unique identifier for the dashboard. You can find the identifier by viewing a dashboard in the Power BI Service. The identifier is in the URL.
* Group ID: Enter the unique identifier for the group. You can find the identifier by viewing a dashboard or report in the Power BI Service. The identifier is in the URL.
* Tile ID: Enter the unique identifier for the dashboard tile. You can find the identifier by entering the focus mode for a tile when viewing a dashboard in the Power BI Service. The identifier is in the URL.
= Other Settings for Power BI Content =
You can also configure how the content is embedded including whether to show the filter pane or page navigation along with the language (defines the language Power BI uses for localization and locale format (defines the text formatting that powerBI uses for dates, currency, etc.). Finally, you can set the default width and height for the container in pixels or as a percentage.
= Important Cache Notes and Fixes =
When installing or upgrading this plugin you may run into display errors when using a CDN, cache plugin or security plugin. The following can be done to fix most caching/security plugin issues.
* Manually purge/clear your plugin and browser cache
* Whitelist the /wp-json path in your security plugin, cache or CDN settings to allow updated data to always be returned.
* Lower your cache timer to 10 hours or less to allow WP nonces to refresh properly
= Embedding Content in WordPress =
Once the Power BI content is created in WordPress, you can embed it anywhere with a shortcode. The shortcode accepts the unique identifier for the Power BI content (visible from "All Power BI Items") and an optional width and height to customize the size of the content where it is being embedded, if you want to override the default width and/or height for the content.
[powerbi id=X width=X height=X]
You also can use a shortcode to display content based on the Power BI Embedded resource state. This shortcode allows you to show content when the resource is active and other content when the resource is paused.
Display the content when resource is active.
[powerbi_resource]
Resource is active.
[/powerbi_resource]
Display the content when resource is paused.
[powerbi_resource state="Paused"]
Resource is paused.
[/powerbi_resource]
Learn more about states. [https://docs.microsoft.com/en-us/rest/api/power-bi-embedded/capacities/getdetails#state](https://docs.microsoft.com/en-us/rest/api/power-bi-embedded/capacities/getdetails#state)
== Filters ==
The plugin is able to filter *Reports* using the [https://github.com/Microsoft/PowerBI-JavaScript/wiki/Filters](Report Level Filters) API functions in PowerBI embedded. To use filters you need to pass the filter object in the querystring as a serialized JSON string.
Example
var relatedFilterObj = [{
$schema : "http://powerbi.com/product/schema#basic",
target : {
table : "Countries",
column : "Country",
},
operator : "=",
values : [country]
}
];
var relatedURL = pageURL + "?filters=" + encodeURIComponent(JSON.stringify(relatedFilterObj));
== Applying Slicers ==
The plugin can also apply Slicers before the report loads based on passing stringified JSON in the URL. Read more about [Slicers](https://github.com/Microsoft/PowerBI-JavaScript/wiki/Slicers)
**Example**
var slicers = [
{
selector : {
$schema: "http://powerbi.com/product/schema#visualSelector",
visualName: "fee64d853d2c3e579085"
},
state : {
filters : [
{
$schema: "http://powerbi.com/product/schema#basic",
target : {
table : "Tools",
column : "Tool"
},
operator: "In",
values: ["Information Operations"],
}
]
}
}
];
var relatedURL = pageURL + "?slicers=" + encodeURIComponent(JSON.stringify(slicers));
== Installation ==
1. Visit 'Plugins > Add New'
1. Search for 'Power BI Embedded'
1. Activate Power BI Embedded for WordPress from your Plugins page.
== Frequently Asked Questions ==
N/A
== Screenshots ==
1. Main settings screen.
2. Screen to add a Power BI item.
3. Example Power BI report.
== Changelog ==
= 1.0 =
* Initial release.
= 1.0.1 =
* Updated the Power BI JavaScript assets from v2.4.6 to v2.5.1
* Add scheduling feature to the Power BI setting page to start and stop resource automatically.
* Add fields to the Power BI setting page to configure Subscription ID, Tenant ID, Resource Group etc.
* Add shortcode to display content based on Power BI resource's capacity status.
= 1.0.2 =
* Added transparent background option.
* Added page name configuration for reports.
= 1.1.0 =
* Added abiltiy to use filters on report
* Updated documentation on using filters
* Increased timeout so report would still work after being open for an hour
* Updated Power BI JavaScript assets from v2.5.1 to v2.6.6
* Added url-search-params-polyfill to be backwards compatible with IE11
= 1.1.1 =
* Added support for caching plugins (must not cache /wp-json/wp/v2/powerbi/getToken directory)
* Attempt at fixes for WP Bakery theme
= 1.1.2 =
* More fixes for WP Bakery theme (upgrade cmb2 library)
= 1.1.3 =
* Fix for initial setup that was causing occassional authentication errors.
* Update Power BI library.
= 1.1.4 =
* Corrected static call of non static Oath get_token() request to correct singleton flow of get_instance() to call the private construct
* Powerbi-client javascript library udpated to v2.19.1
* CMB2 library update
* Added initial rewrite flush the first time register post type is called
* Created uninstall.php to remove options and transients on uninstall
* Added credentials check for Power BI settings page to prevent uncessary curl call and php warning
* Created new class for endpoints and moved getToken() to the new class
* Created new flow for report generation instead of using shortcodes. Report data now generated through new JS standalone file and functions.
* Added security escapes and sanitization in report data collection and display.
* Mobile settings and support added for reports
= 1.1.5 =
* Cache mitigation for rest endpoints
* Transient cleanup on removal and activation
= 1.1.6 =
* Revert to v1.1.3 due to regressions
= 1.1.7 =
* Fix for PHP 8.0
== Upgrade Notice ==
= 1.0.1 =
This release contains bug fixes from the Power BI library.
= 1.0.2 =
This release contains feature enhancements.
= 1.1.0 =
This release contains feature enhancements and bug fixes.
= 1.1.1 =
This release contains important bug fixes.
= 1.1.2 =
This release contains important bug fixes.
= 1.1.3 =
This release contains important bug fixes.
= 1.1.4 =
This release contains important bug fixes and new features.
= 1.1.5 =
This release contains important bug fixes.
= 1.1.6 =
This release contains important bug fixes.
= 1.1.7 =
This release contains important bug fixes.