Adding a Dynamic Image to a Document

You can embed within a MicroStrategy Web document images that are generated by an external or a third-party application and stored in a remote location These images can be static images, or they can be dynamic images that are created at runtime based on data sent in the image request. For example, you can create a document which includes a map that is generated by an external application using report data passed by MicroStrategy Web at runtime. In addition, you can specify that this map be generated with different data for different users, using only the data to which each user has access based on the security filter for that user.

The process is straightforward. You compile a custom page in MicroStrategy Web which simply runs the report when executed. This page has an add-on, which is used to redirect the image request along with the state of the report bean to the external application. The external application uses the state of the report bean to extract the data, create the map, and stream it back to the client. The diagram below illustrates a high-level view of the sequence of events in this process.

In the sample code provided for this scenario, the external or third-party application is simply another MicroStrategy application in a different location to which the image request and the state of the report bean is passed. Thus, the document is executed in MicroStrategy Web, and the dynamic image is retrieved from another MicroStrategy environment that acts as an external or a third-party application. Thus, the add-on sample code provided for this scenario includes a URL that points to MicroStrategy (in a .NET environment). To change the URL so that it points to a J2EE environment or to specify an external or a third-party application, you must modify the add-on code.

This customization can be accomplished using either of the following methods:

Deploying the plug-in provided with MicroStrategy SDK
Using the Web Customization Editor to create a plug-in

Deploying the plug-in provided with MicroStrategy SDK

MicroStrategy SDK provides a plug-in (ZIP file) that can simply be extracted to thepluginsfolder to view the customization in MicroStrategy Web. The following steps guide you in locating the plug-in and deploying it.

Access the plug-in: JSP version or ASP .NET version.
Extract the plug-in to the plugins subfolder inside the MicroStrategy Web installation folder.
Launch MicroStrategy Web to view the customization.

Using the Web Customization Editor to create a plug-in

MicroStrategy SDK provides a Web Customization Editor that can be used to create a customization plug-in. The following steps guide you in creating the plug-in and deploying it.

Launch the Web Customization Editor.
Click on MicroStrategy Web Configuration inside the Application Settings view to expand the hierarchical tree. The expanded list comprises the different settings that can be modified to perform customizations.
Right-click on Pages and select New Empty Page.
On the New Configuration Element dialog, enter ImageMapAddOnPage in the Name text field for the new page and click OK.
On the Basic Properties tab for ImageMapAddOnPage, change the description in the Descriptor text field to Page with Image Map Add-on.
Save your changes.
Right-click ImageMapAddOnPage(Page with Image Map Add-on) and select Create New Add-on. This launches the Add-on Creation Wizard.
Click Browse to select the source folder for the project.
Enter com.microstrategy.sdk.samples.addons in the Package text field.
Enter ImageMapAddOn in the Name text field.
Enter Add-on for image map in the Description text field.
Check the Add custom logic after fetching data from Intelligence Server (postCollectData)checkbox.
.
Click Next.
Click Finish. ImageMapAddOn.java opens in the editor. Replace the template code with the logic to redirect the image request to a remote URL, where the application that generates the image is located, and pass it the ID and state of a report.

A sample, ImageMapAddOn.java, is provided for you in the plug-ins folder. This file contains logic to redirect the application to a remote URL and pass parameters to it, including the ID and state of a report. The remote URL is the URL to access the external application that creates the dynamic image to be inserted into the document. For this scenario, you can simply copy this code and paste it over the template code.
Save your changes.
Double-click imageMapAddOn(Page with Image Map Addon) and click the Add-on Properties tab at the bottom in the right frame.
With com.microstrategy.sdk.samples.addon.ImageMapAddOn selected in the Add-ons section, click Add New in the Add-on Properties section.
Select imageServerURL, and click >>.
Click OK.
In the Add-on Properties section, add the value for the imageServerURL property shown in bold below, substituting the correct external application server name.
- name: imageServerURL
- type: string
- source: const
- value: http://<WebServer>/MicroStrategy/asp/Main.aspx
Save your changes.
Expand imageMapAddOn(Page with Image Map Addon), right-click Beans, and select New Bean
On the New Bean Wizard, enter the following information:
- Name: rb
- System Bean: ReportBean
- Persistence Mode: Request
This report bean is executed on MicroStrategy Intelligence Server to generate the data that the external application uses to create the dynamic image in the document.
Click Next.
Since there are no features associated with this bean, click Next.
Since there is no event-handler associated with this bean, click Next.
On the Initialization Properties tab, use the >> arrow to select the following properties:
- graphBeanName
- maxWait
- pollingFrequency
Click Next.
On the Request Properties tab, use the >> arrow to select the following properties:
- objectID
- viewMode
Click Next.
Review the property information and click Finish.

On the Initialization Properties tab, change or enter the values to those shown in the table below, as required.

Name	Type	Source	Value
graphBeanName	string	const	gb
maxWait	int	const	2000
pollingFrequency	int	const	100

On the Request Properties tab, change or enter the values to those shown in the table below, as required.

Name	Type	Source	Value
objectID	string	request	reportID
viewMode	int	request	reportViewMode

Save your changes.
Create a document and insert a dynamic image in the document. This dynamic image is generated by the external application. Use the following code as a guide for creating the source for the dynamic image:

J2EE environment:
Copy
```
http://<WebServer>/MicroStrategy/servlet/mstrWeb?evt=4001&src=mstrWeb.ImageMapAddOnPage.4001&reportViewMode=2&reportID=5E71925A411428F4EC24A9B28573D3AB
```
.NET environment:
Copy
```
http://<WebServer>/MicroStrategy/asp/Main.aspx?evt=4001&src=Main.aspx.ImageMapAddOnPage.4001&reportViewMode=2&reportID=5E71925A411428F4EC24A9B28573D3AB
```
The sample code above points to the new page you created, which has an add-on that redirects your MicroStrategy Web application to the server that houses the external application. In your production code, substitute the name of your Web Server for <Web Server> and the name of your custom page if you did not use ImageMapAddOnPage. Replace the report ID (5E71925A411428F4EC24A9B28573D3AB in the sample URL) with the ID for the report that generates the data used by the external application and add any additional parameters required by the API for the external application. (Because this scenario uses a remote MicroStrategy application to generate a report graph as the dynamic image, it passes the view mode of the report as graph (reportViewMode=2).

Do not use a prompted report. The document cannot display the image when a prompted report is used.

When you run the document, it includes the dynamic image that was generated by the external application.

If you use MicroStrategy Web as the external application, it must also be connected to the same MicroStrategy Intelligence Server to which your MicroStrategy Web is connected, that is, the server from which the data used to generate the image is retrieved.

Launch MicroStrategy Web to view the customization.

If you want to pass additional parameters in the URL to be processed by the add-on, you need to implement a pre-processing function. A typical example is the document including a group-by field that you want to use to determine the data used to generate the image for each user. If the group-by field is Regions, for instance, you have four pages— one for each of the regions— East, West, North and South. For this scenario, one unique image must be created for each page (with a total of four pages), where the report has to be run for the East region, then the West, the North, and the South. The code to pass in the parameters needed for this example corresponds to the sample code shown below:

J2EE environment:

Copy

http://<WebServer>/MicroStrategy/servlet/mstrWeb?evt=4001&src=mstrWeb.ImageMapAddOnPage.4001&reprtViewMode=1&
reportID=5E71925A411428F4EC24A9B28573D3AB&region=[regionID

.NET environment:

Copy

http://<WebServer>/MicroStrategy/asp/Main.aspx?evt=4001&src=Main.aspx.ImageMapAddOnPage.4001&reportViewMode=1&
reportID=5E71925A411428F4EC24A9B28573D3AB&region=[regionID]

In addition to the post processing, you need to implement an add-on to extract the regionID passed in and run the report by answering the region prompt in the report so that each report state includes only the report data for a specific region. As a result, the image that is generated is be specific for each region.