oproarts designer for force · oproarts designer for force.com - report engine developer guide 1....

OPROARTS Designer for Force.com Report Engine

Developer Guide

：Tel +81 3-5765-6510

Fax: +81 3-5765-6560

Japan.

Web: www.opro.net/en

OPRO Japan Co., Ltd. 6F, Shibashin-Mita Bldg., 3-43-15,

Shiba, Minato-Ku, Tokyo, 105-0014,

Copyright © 1997-2010 OPRO Japan Co., Ltd. All rights reserved.

OPROARTS Designer for Force.com - Report Engine Developer Guide

Table of Contents

Abstract.........................................................................................................................ii

1. Introduction to OPROARTS Designer for Force.com .........................................1

2. Getting Started.........................................................................................................2

3. Report Engine Programming Interface ...............................................................12 3.1. URL API ...........................................................................................................13 3.2. Apex API...........................................................................................................14

4. Report Engine Integration ....................................................................................15 4.1. Basic Integration ...............................................................................................16 4.2. Advanced Integration ........................................................................................18

5. Operations Supported by RE................................................................................23 5.1. Mail Merge and Download Operation ..............................................................24 5.2. Mail Merge and Attach Operation ....................................................................30 5.3. Mail Merge and Email Operation .....................................................................35 5.4. Mail Merge and Fax Operation.........................................................................42


i


Table of Figures

Figure 1 – Installed Packages Section in the Force.com Account.................................2 Figure 2 – Click the OPROARTS Designer for Force.com Link ..................................3 Figure 3 – Click the Manage Licenses Button...............................................................3 Figure 4 – Click on the Add Users Button.....................................................................4 Figure 5 – Assign Licenses to a Select Set of User .......................................................4 Figure 6 – The Licensed User are Displayed.................................................................5 Figure 7 – Create a new OPROARTS ‘AD’..................................................................5 Figure 8 – Add OPROARTS Users to ‘AD’..................................................................6 Figure 9 – OPOROARTS Designer tab .........................................................................6 Figure 10 – Move to the Profile Section in the Force.com Account .............................7 Figure 11 – Editing the Force.com Free User Profile....................................................8 Figure 12 – Editing the Custom App Settings ...............................................................8 Figure 13 – Editing the Custom Tab Settings................................................................9 Figure 14 – Force.com Visualforce Pages List..............................................................9 Figure 15 – Click the Security Link of a Selected Visualforce Page...........................10 Figure 16 – Enable Force.com - Free User profile access for pdfProfileUsers

Visualforce page.......................................................................................10 Figure 17 – Enable Force.com - Free User profile access to other relevant Visualforce

pages.........................................................................................................11 Figure 18 – Click 'Button and Links' ...........................................................................16 Figure 19 – Place custom links ....................................................................................17 Figure 20 – Click custom link to generate REs PDF outputs ......................................17 Figure 21 – OPROARTS Designer for Force.com components..................................20 Figure 22 – Force.com Sandbox list ............................................................................21 Figure 23 – Package install error .................................................................................22 Figure 24 – Identify the template.................................................................................24 Figure 25 – Template id...............................................................................................24 Figure 26 – Template ‘Name’ and ‘Namespace prefix’ ..............................................25 Figure 27 – RE Template.............................................................................................26 Figure 28 – Template controller Id for Profile.............................................................27 Figure 29 – Batch report with attach action.................................................................33 Figure 30 – Get email template ID ..............................................................................37 Figure 31 – Visualforce email template source ...........................................................38 Figure 32 – Batch report with Email action.................................................................40 Figure 33 – Batch report with Fax action ....................................................................45


ii


Abstract This document describes OPROARTS Designer for Force.com and its integration interface in detail. The latest copy of this guide and other useful developer resources can be found at https://www2.opro.net/en_arts/download.html


iii

https://www2.opro.net/en_arts/download.html


OPROARTS Designer for Force.com


iv


1. Introduction to OPROARTS Designer for Force.com

OPROARTS Designer for Force.com is a PDF document designing, generation and delivery as well as Visualforce page designing solution for Force.com. It consists of a web based WYSIWYG, Drag & Drop designer named OPROARTS Designer and a document generation and delivery engine named Report Engine (RE). Force.com applications can easily integrate with RE and provide these functionalities to its users with a minimum of effort. M

ain features of Report Engine are 1. Mail merge Salesforce (SF) data to various recipient groups, namely SF Users, SF

Contacts and SF Leads and generate PDF outputs.1

2. Attach mail merged PDF outputs to any given SF object.2

3. Deliver mail merged PDF documents to respective group members as email attachments or fax messages.3

4. Easily integrate with Force.com applications with zero or minimal integration code.4

5. Produce high quality PDF outputs with built-in pagination using well structured Templates.5

RE Works in all SF editions, including Force.com, but doesn’t support Contact Manager Edition. RE is not bounded to any SF object. Therefore RE works even in the Force.com platform edition where CRM objects are not available. For Professional Edition, there are certain restrictions since Apex integration codes will not execute until it passes a security review by Salesforce. With above features RE will fit in to any Apex/Visualforce developer’s tool kit as a utility application enabling them to build solutions offering all above features to their users. Note :

1 Leads and Contacts are not available in the default Force.com edition. Therefore it is only possible to mail merge to SF Users in this edition. 2 To attach the PDF document to any given object the end-user should have the relevant privileges. 3 To deliver as a fax messages you need to subscribe to a commercial mail2fax service. 4 Two levels of integration are possible: basic and advanced. Basic integration doesn’t require integration codes, but its usage will have limitations. 5 RE’s Visualforce templates follow a free form structure with its own set of report elements.


1


2. Getting Started

Follow these common steps to begin using OPROARTS Designer for Force.com for all account types except Force.com free edition. Followings are described relate to Developer Edition account.

1. Sign up for a free Salesforce.com Developer Edition account. http://www.developerforce.com/events/regular/registration.php

2. Install OPROARTS Designer for Force.com from AppExchange.

You’ll be able to use this trial-version for 30-days.

https://sites.secure.force.com/appexchange/listingDetail?listingId=a0N30000003HtFsEAK

3. Move to Setup\ App Setup \ View Installed Packages section in the Force.com account to manage licenses.

Figure 1 – Installed Packages Section in the Force.com Account


2

http://www.developerforce.com/events/regular/registration.php




4. Click the OPROARTS Designer for Force.com link in the Package Name column of the OPROARTS Designer for Force.com package.

Figure 2 – Click the OPROARTS Designer for Force.com Link

5. Click the Manage Licenses button in the Installed Package Detail section of the

OPROARTS Designer for Force.com package and move to the Licensed Users section.

Figure 3 – Click the Manage Licenses Button


3


6. Click on the Add Users button in the Licensed Users section.

Figure 4 – Click on the Add Users Button

7. Select the user(s) you want to assign licenses from Available Users section. (The

OPROARTS Designer for Force.com trial version will allow only two users to be selected.)

Figure 5 – Assign Licenses to a Select Set of User


4


8. Click the Add button and confirm your user selection process.

Figure 6 – The Licensed User are Displayed

Enabling OPROARTS Designer

Follow the below steps to enable OPROARTS Designer for developer account users.

1. Select the OPROARTS Designer for Force.com from the force.com apps dropdown menu on the top right of your Salesforce page.

2. Press the ‘OPROARTS’ tab located at the upper left corner of the

OPROARTS Designer Interface and set ‘AD’ as OPROARTS field value and add suitable CID value provided by OPRO Japan Co., Ltd. and press ‘Save’ Button.

Figure 7 – Create a new OPROARTS ‘AD’


5


3. Add OPROARTS Users to above OPROARTS ‘AD’ with 'New OPROARTS User' button. Please make sure to also add the currently signed in user to the OPROARTS users.

Figure 8 – Add OPROARTS Users to ‘AD’

4. Press the OPROARTS Designer tab. The 'START’ button will appear in the

OPROARTS Designer tab only if the currently signed in user has been added to the OPROARTS Users list.

Figure 9 – OPOROARTS Designer tab


6


Special Configurations Steps for Force.com free edition users: You need to enable Force.com platform users to use Report Engine(RE) features of OPROARTS Designer for Force.com. In general in the Force.com platform, any user must be authorized to use any custom application installed by changing their user profiles by a user with sufficient user privileges. First follow the steps up to 6, under ‘Getting Started’ section and then follow below steps to enable OPROARTS Designer for Force.com platform users.

1. Move to the Setup\ Administration Setup\Manage Users\Profiles section

in the Force.com account.

Figure 10 – Move to the Profile Section in the Force.com Account


7


2. Choose the Edit option of the Force.com–Free User profile.

Figure 11 – Editing the Force.com Free User Profile

3. Set OPROARTS Designer for Force.com as Default in the Custom App

Settings section.

Figure 12 – Editing the Custom App Settings


8


4. Set OPROARTS and OPROARTS Designer as Default on in the Tab settings/Custom Tab Settings section and press the Save button.

Figure 13 – Editing the Custom Tab Settings

5. To enable profile access to Visualforce pages, go to the Setup\App

Setup\Develop\Pages section in the Force.com account.

Figure 14 – Force.com Visualforce Pages List


9


6. Click the Security link of the Visualforce page, where the label name is Profile Users Report and the Name is pdfProfileUsers page.

Figure 15 – Click the Security Link of a Selected Visualforce Page

7. Add the Force.com - Free User entry from the Available Profiles section to

the Enabled Profiles section of the list box by pressing the Add button and press the Save button.

Figure 16 – Enable Force.com - Free User profile access for pdfProfileUsers

Visualforce page


10


8. Follow the above mentioned procedure for all required Visualforce pages in the Setup\App Setup\Develop\Pages section.

Figure 17 – Enable Force.com - Free User profile access to other relevant

Visualforce pages

9. Follow the steps in above ‘Enabling OPROARTS Designer’ section. Packaging issues

Now you are ready to use RE in OPROARTS Designer for Force.com to solve your reporting related problems. This document describes in detail how to integrate with RE. Please see Chapter 4.2 for more details regarding packaging your integration code to use in your production environment.

Free Templates

Two free Visualforce Templates will be installed with RE in the usual Visualforce Page location. These two Templates will have a namespace prefix of OPROARTS010 and they are based on Salesforce Profiles object. Note :

Developer resources are available for download at https://www2.opro.net/en_arts/download.html

Optionally, the same templates can be downloaded and used from the below mentioned download site. In this case you will need to edit the templates to replace the ‘c:’ namespace prefix with ‘OPROARTS010:’.


11



3. Report Engine Programming Interface

Report Engine supports four main operations: • Mail Merge and Download • Mail Merge and Attach • Mail Merge and Email • Mail Merge and Fax

Above operations are described in detail later in Chapter 5. Report Engine provides two kinds of programming interfaces for integrating applications to call above operations:

URL API RE provides a set of parameters to invoke the download, attach, email and fax operations of RE with the URL API.

Apex API

Apex API provides an Apex programming interface to invoke the download, attach, email and fax operations of RE.


12


3.1. URL API

With the URL interface developers can call supported operations of the Report Engine using the action attribute and executing the Report Engine URL.

The URL API follows the following syntax:

https://[namespaceprefix].[sfinstance].visual.force.com/apex/ReportEngine?[attributes]

E.g.: httts ://oprarts010.ap1.visual.force.com/apex/reportEngine?action=download&tem plateControllerId={!Opportunity.Id}& templateName=Quotation https

Programmatically, the action URL can be build with the following method.

private String getPageUrl() { String hostName = ApexPages.CurrentPage().getHeaders().get('Host'); return 'https://' + hostName + '/apex/OPROARTS010_reportEngine'; }

Source Listing 3.1 – getPageUrl to call RE And the necessary attributes can be set as shown below:

Public Pagereference getMerge() { Pagereference mergePage = new Pagereference(getPageUrl()); mergePage.getParameters().putAll(getMergeParameters()); return mergePage; }

Source Listing 3.2 – getMerge to execute Merge action

Public Map<String, String> getMergeParameters() { Map<String, String> parameterMap = new Map<String, String>(); parameterMap.put('templateControllerId', userInfo.getProfileId()); parameterMap.put('templateId', '066900000004PfH'); /* Id 'pdfProfileUsers' for this salesforce account */ parameterMap.put('templateId', userInfo.getUserId()); return parameterMap; }

Source Listing 3.3 – getMergeParameters to add attributes Additional developer resources are available for download at https://www2.opro.net/en_arts/download.html


13



3.2. Apex API

Report Engine provides another type of programming interface, the Apex interface, to call its operation using method invocations.

The Apex class, ReportEngineController, provides necessary methods to call RE operations. Please see the RE API docs for more details.

E.g.: ‘Mail Merge and Download’ operation can be called as shown below:

public PageReference viewPdf() { OPROARTS010.ReportEngineController reqController = new OPROARTS010.ReportEngineController(); PageReference viewPage = reqController.downloadPdf(getMergeParameters()); return viewPage; }

Source Listing 3.4 – Using downloadPDF method To set the parameters you can use the following Apex method:

public Map<String, String> getMergeParameters() { Map<String, String> parameterMap = new Map<String, String>(); parameterMap.put('templateControllerId', userInfo.getProfileId()); parameterMap.put('templateId', '066900000004PfH'); /* Id 'pdfProfileUsers' for this salesforce account */ parameterMap.put('targetIds', userInfo.getUserId()); return parameterMap; }

Source Listing 3.5 – adding parameters Additional developer resources are available for download at https://www2.opro.net/en_arts/download.html


14



4. Report Engine Integration

RE is a utility application mainly for developers enabling them to build integrated solutions. There are two levels of integration possible with RE.

Basic integration -using URL API, with zero integration code.

Advanced integration -using URL API or Apex API, with Apex integration code.


15


4.1. Basic Integration

Integration using URL API, with zero integration code

Basic integration of RE can be done simply by building a Custom Link or a Button where the necessary parameters to perform the desired action are appended to the action URL. RE will process the specified Template and execute the desired action.

Integration steps

Basic integration involves three steps: a. Create a RE Template. b. Create a Custom Button or Link to invoke the action URL. c. Place the link or button in a suitable page layout.

Step a. Create RE Template.

Two free Visualforce Templates will be installed with RE in the usual Visualforce Pages location. These two pages will have a namespace prefix of OPROARTS010 and this is based on SF Profile object.

Additional developer resources are available for download at https://www2.opro.net/en_arts/download.html

Step b. Create a Custom Button or Link to call URL API of RE

You need to build a Custom Button or Link to call RE. Please see above Chapter 3 (3.1) for more details on URL API.

Figure 18 – Click 'Button and Links'


16



Step c. Place the link or button in a suitable page layout

Figure 19 – Place custom links

Now you can click the link to view the PDF output generated by Report Engine

Figure 20 – Click custom link to generate REs PDF outputs

In the above mentioned Basic Integration there are no integration codes and classes involved. Therefore any user with a basic knowledge of Visualforce and CSS can use RE Templates to transform their plain looking PDF outputs to RE’s PDF outputs within a short period of time.


17


Usage scenarios

This level of integration is suitable for following types of organizations

1. Organization that have already installed native AppExchange solutions such as order management systems, other quote solutions, etc., in their production environment and are not happy with the quality of their PDF outputs. Since RE is a Visualforce components and Apex classes based application other native applications can easily integrate RE and communicate with it with the provided interface to generate a quality PDF outputs.

2. Organizations that use Salesforce Professional edition for their operations.

Basic level integration allows them to integrate to RE without having to obtain security review for integration codes.

Salesforce Professional edition does not support Apex codes unless they pass the security review. So any integration code you write to work with RE in your Developer edition will need to pass their review in order to port it to the Professional edition.

3. Any organization looking for quick implementation of PDF output solutions.

Note :

Although it is possible to use basic integration using the URL interface of RE in your production environment, it is always a best practice to build and test your integration URLs in a sandbox or developer edition before using the URL in your production environment.

4.2. Advanced Integration

Using URL API or Apex API, with Apex integration code

To use all the features of RE, it is necessary to create a Custom Apex classes to pass dynamic parameters and invoke desired actions. With only a few lines of integration code, developers can integrate RE into their existing applications or create new Custom applications easily. For Example OPROARTS Designer for Force.com is developed using a similar technology.

Integration code will be in Apex classes, and a Custom Button or a Custom Link can be used in any standard or Custom Tab to launch RE via this Apex class.

Important:

Force.com platform developers need to create a sandbox login to build their integration code. You can do this by going to Setup Administration Setup Data Management Sandbox and clicking on the New Sandbox button.

Integration steps

Advance integration involves four steps: a. Create RE Template b. Create Custom Apex class to call RE c. Create a Button or Link to execute the Apex class d. Place the link or the button in a suitable page layout


18


Step a. Create RE Template.

Two free Visualforce Templates will be installed with RE in the usual Visualforce Page location. These two pages will have a namespace prefix of OPROARTS010 and based on SF Profiles object.

Additional developer resources are available for download at https://www2.opro.net/en_arts/download.html

Step b. Create a Custom Apex class to call RE

When you are integrating with Apex classes you have two options to call RE:

1. Using URL API of RE 2. Using Apex API of RE

In both methods you need to build RE parameters in a map before executing the desired action.

Please see Chapter 3 (3.1) for more details on URL API of RE. Please see Chapter 3 (3.2) for more details on Apex API of RE.

1. Using URL API of RE

Public Pagereference getMerge() { Pagereference mergePage = new Pagereference(getPageUrl()); mergePage.getParameters().putAll(getMergeParameters());

return mergePage; }

Source Listing 4.1 – Invoke getMerge to execute download


Source Listing 4.2 – getMergeParameters to add parameters Note : If the action is not specified, download will be assumed as the default.


19



2. Using Apex API of RE

public PageReference viewPdf() {

OPROARTS010.ReportEngineController reqController = new OPROARTS010.ReportEngineController(); PageReference viewPage = reqController.downloadPdf(getMergeParameters()); return viewPage;

Source Listing 4.3 – ReportEngineController#downloadPdf API

}

Packaging RE based development in your environment

Once you have built and tested your integration codes in your sandbox or developer edition environment you need to package it to use in your production environment. When doing so, OPROARTS Designer for Force.com will be added as a dependent package of your integration package, automatically. Then when you are installing your integration package in your production environment, you’ll be notified if RE is not available in your production environment.

Please see below images for an illustration.

For Developer platform users

In your developer environment, package your integration code as shown below: Go to Setup App Setup Create Packages Here you will notice that OPROARTS Designer for Force.com components are listed under Package Components.

Figure 21 – OPROARTS Designer for Force.com components


20


For Force.com platform users:

Login to your Sandbox environment

Figure 22 – Force.com Sandbox list

Package your integration code

You will get the installation URL similar to below: httts ://test.salesforce.com/?startURL=%2Fpackaging%2FinstallPackage.apexp%3 Fp0%3D04tT00000006Qqb You must replace the initial portion (scheme name://registered domain name.top level domain) of the URL with https://login.salesforce.com/

Now you can install the package with httts ://login.salesforce.com/?startURL=%2Fpackaging%2FinstallPackage.apexp%3 Fp0%3D04tT00000006Qqb https

https


21

https://login.salesforce.com/


Package dependency

When you are installing your integration package in your production environment and if OPROARTS Designer for Force.com is not installed there as yet, you’ll see the following error being prompted.

Figure 23 – Package install error

I mportant:

If you are a Salesforce Professional Edition customer, your integration code will not run until it passes the security review conducted by SF. You need to either obtain a security review certificate or use only basic URL interface integration, without any integration codes.


22


5. Operations Supported by RE

There are four main operations supported by RE:

1. Mail Merge and Download 2. Mail Merge and Attach 3. Mail Merge and Email 4. Mail Merge and Fax

Following sections describe the main operations supported by RE. The basic integration usage and the advanced integration usage are explained under each of those operations. Dealing with batch reports which are supported only by the 2nd, 3rd and 4th operations is also described there. RE provides free sample Templates as guidance for creating complex PDF Templates. In this document we are using these Templates to illustrate the sample usage of each operation. Additional developer resources are available for download at https://www2.opro.net/en_arts/download.html


23



5.1. Mail Merge and Download Operation

RE supports mail merging to SF Users, SF Leads and SF Contacts. A single PDF document will be generated with repeating pages for each mail merge targetIds.

Follow the below steps to implement this operation:

a. Identify the Template

Templates can be specified in one of three ways: 1. By providing the templateId

E.g.: Go to Setup Develop Pages and Click on page name

Figure 24 – Identify the template

Now you can copy the relevant templateId.

Figure 25 – Template id

templateId=066900000004PfH

2. By providing the templateName with the templateNameSpace

E.g.: Go to Setup Develop Pages and select the appropriate Name and Namespace Prefix.


24


Figure 26 – Template ‘Name’ and ‘Namespace prefix’

templateName=pdfProfileUsers, templateNamesapce=OPROARTS010

3. By providing the templateURL

E.g.: templateURL should be following format:

If NamespacePrefix exists: httts ://customerSalesforceURL/apex/NamespacePrefix__pageName or httts :// [namespaceprefix].[sfinstance].visual.force.com/apex/pageName https

https

If NamespacePrefix does not exists httts ://customerSalesforceURL/apex/pageName or httts ://c.[sfinstance].visual.force.com/apex/pageName

Sample URL for templateURL(If Namespace Prefix is ‘OPROARTS010’) httts ://ap1.salesforce.com/apex/OPROARTS010__pdfProfileUsers or httts ://OPROARTS010.[sfinstance].visual.force.com/apex/ pageName

It is required to identify the Template using either of above three ways. Failure to resolve the Template will throw an error.

https

https

https

https


25


b. Specify the Template controller Id

Every RE Template will have a StandardController defined in the Visualforce Template.

Figure 27 – RE Template

This parameter is optional and if omitted no data will appear in the output

Go to Setup Manage Users Profiles and select the appropriate Profile(E.g.: System Administrator) to get the profile Id. Then,

templateControllerId=00e90000000EEWW


26


Figure 28 – Template controller Id for Profile

c. Specify the mail merge targets

Provide target Salesforce object Ids to retrieve mail merge data from.

Supported values are Ids from Users, Leads and Contacts objects.

Multiple mail-merging is possible by specifying a comma separated list of targetIds. In this case each targetId should belong to the same SF object.

For example if targetIds=00390000001j2Kw, 00390000001j2Kx is specified,

In the same PDF document, pages will be repeated for each targeteds with their target names appearing in two separate pages.

If the targetIds are not specified or invalid targetIds are given, RE will pop up an error message.

When multiple targetIds are specified and if any one of the specified targetId is found to be invalid, RE will pop up an error message. This is also true for miss matching targetIds types.

d. Specify the action

For ‘Mail Merge and Download’ operation, the action should be specified as download. If this value is omitted, download action will be used as the default value.


27


How to perform this operation using basic integration:

1. Edit and Save the Visualforce Template 2. Build the action URL

With URL interface

Create the action URL by appending the above mentioned a to d parameters to the report engine URL.

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?templateName=pdf UserProfile&templateControllerId=00e90000000EEWW &targetIds=00390000001j2Kw, 00390000001j2Kx&action=download

https

3. Create a Button or a Link for this URL. 4. Place the Button or the Link in a suitable page layout.

How to perform this operation using advanced integration:

1. Edit and Save the Visualforce Template. 2. Create an Apex class.

With URL interface Programmatically build the URL as follows:

Write a method to execute the action URL

Public Pagereference getMerge() { Pagereference mergePage = new Pagereference(getPageUrl()); mergePage.getParameters().putAll(getMergeParameters()); return mergePage; }

Source Listing 5.2 – getMerge method to merge

And set above a to d parameters as shown below:


Source Listing 5.3 – getMergeParameters to add parameters

If action parameter is omitted, download will be assumed as the default.


28


With Apex interface

public PageReference viewPdf() {

OPROARTS010.ReportEngineController reqController = new OPROARTS010.ReportEngineController(); PageReference viewPage = reqController.downloadPdf(getMergeParameters()); return viewPage; }

Source Listing 5.4 – ReportEngineController#downloadPdf API

3. Create a Button or a Link for this URL. 4. Place the Button or the Link in a suitable page layout.


29


5.2. Mail Merge and Attach Operation

RE supports attaching the mail merged document to any given Salesforce object having attachment permission.

This operation assumes that you have successfully implemented and tested the ‘Mail Merge and Download’ operation. Here we’ll discuss how to add the attaching feature.

First follow the steps a to c mentioned in section 5.1 Mail Merge and Download operation Then follow the below steps to implement this operation:

a. Name the attaching document

Provide a suitable name for the document to be attached. If omitted, the document will be attached with the name of the Template as the attachment name.

E.g.: AttachmentName=UserMemo20091201

It is allowed to re-use the same name in multiple attach operations.

b. Identify the attaching parent object (Opportunity,Account,etc..)

Provide the id of the object where you want the document to be attached to. E.g.: AttachParentId=00690000002Ctb7

When this parameter is omitted, generated PDF document will be attached to Salesforce object corresponding to templateControllerId.

It is important to note that either the AttachParentId or the templateControllerId is required to perform this action.

c. Specify the action

For mail merge and attach operation the action should be specified as attach.

Batch report attach operation:

With RE it is possible to generate multiple PDF documents for multiple templateControllers each with multiple targets and attach them under respective Salesforce objects with separate attachment names at once.

Specify multiple templateControllerIds

The syntax of specifying multiple templateControllerIds in a batch request as opposed to templateControllerId parameter in a single request is ‘templateControllerId_x’. Where ‘x’ is a positive integer. For example in specifying 3 templateControllerIds in a batch request the parameter names could be templateControllerId_1, templateControllerId_2, templateControllerId_3… etc.


30


To generate two PDF documents related to two different profile ids ‘00e90000000EEWW’ and ‘00eA0000000t6Q3’ using RE Templates, templateControllerId parameters could be specified as follows. templateControllerId_1=00eA0000000t6Q3 templateControllerId_2=00eA0000000ZEu0

Specify multiple targetIds

Similarly the syntax of specifying targetIds in a batch request to a particular templateControllerId is ‘targetIds_x’. Where ‘x’ is a positive integer of the relevant ‘templateControllerId’. Multiple targetIds of the same templateControllerId could be specified as comma separated values. Multiple targetIds corresponding to multiple templateControllerIds could be specified as targetIds_1, targetIds_2, targetIds_3 … etc..

To make a batch request with 2 templateControllerIds specified as templateControllerId_1 and templateControllerId_2 and in specifying 1 targetIds (00390000001j2Kw) to templateControllerId_1 and 2 targetIds (00390000001j2Kw, 00390000001j2Kx) to templateControllerId_2, the targetIds parameters should be specified as,

targetIds_1=00390000001j2Kw targetIds_2=00390000001j2Kw,00390000001j2Kx

Then the PDF document related to the templateControllerId_1 will be generated with the target information using Salesforce object of id ‘00390000001j2Kw’ and the PDF document related to the templateControllerId_2 will be generated with the target information using Salesforce objects of ids ‘00390000001j2Kw’ and ‘00390000001j2Kx’.

Note: It is useless to specify targetIds_x without specifying template Contro ller Id_x (where x = 1, 2, 3 …).

Specify multiple attachParentId

Following the same syntax the attachParentId parameter could be changed to attachParentId_1, attachParentId_2, attachParentId_3 … etc.

To attach two different reports under Salesforce objects corresponding to the ids of ‘00690000002Ctb7’ and ‘00690000002Ctb8’, following two parameters have to be specified.

attachParentId_1=00690000002Ctb7 attachParentId_2=00690000002Ctb8

Then report related to the templateControllerId_1 will be attach to the Salesforce object of attachParentId_1 and the report related to the templateControllerId_2 will be attach to the Salesforce object of attachParentId_2.


31


Note: It is useless to specify attachParentId_x without specifying templateControllerId_x (where x = 1, 2, 3 …). Specify multiple attchmentName

Similarly the attchmentName parameter could be changed to attchmentName_1, attchmentName_2, attchmentName_3 … etc.

To attach two different reports with different names, following two parameters have to be used instead of attchmentName parameter.

attchmentName_1=UserMemo20091201a attchmentName_2=UserMemo20091201b

Then report related to the templateControllerId_1 will be attached with the name of ‘UserMemo20091201a’ and report related to the templateControllerId_2 will be attached with the name of ‘UserMemo20091201b’.

Note: It is useless to specify attchmentName_x without specifying templateControllerId_x (x = 1, 2, 3 …).

How to perform this action using basic integration:

Edit the action URL you created for ‘Mail Merge and Download’ action by appending the necessary values for above a-c steps in section 5.2. Mail Merge and Attach Operation.

With URL interface

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?templateName=pdf UserProfile&templateControllerId=00e90000000EEWW&targetIds=00390000001j2Kw,00390000001j2Kx&attachmentName=UserMemo20091201&AttachParentId=00690000002Ctb7&action=attach

Create a Button or a Link for this URL and place it in a suitable page layout.

Note : To attach batch reports, the action URL should be modified as below.

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?templateName=pdf UserProfile&templateControllerId_1=00eA0000000t6Q3& template Controll erI d_2=00eA0000000ZEu0&targetIds_1=00390000001j2Kw&targetIds_2=00390000001j2Kw,00390000001j2Kx&attachParentId_1=00690000002Ctb7&attachParentId_2=00690000002Ctb8&attchmentName_1=UserMemo20091201a&attchmentName_2=UserMemo20091201b&action=attach

https

https


32


Figure 29 – Batch report with attach action

How to perform this action using advanced integration:

With URL interface

Add above a to c steps in section 5.2. Mail Merge and Attach Operation to the same Map object.

public Map<String, String> getMergeAndAttachParameters() { Map<String, String> parameterMap = new Map<String, String>(); parameterMap.put('action', 'attach'); parameterMap.put('attachmentName', getProfileName() + 'Profile Users'); parameterMap.put('attachParentId', getAttachParentId()); parameterMap.put('templateControllerId', userInfo.getProfileId()); parameterMap.put('targetIds', userInfo.getUserId()); parameterMap.put('templateId', '066900000004PfH'); return parameterMap; }

Source Listing 5.5 – getMergeAndAttachParameters to add parameters

Write a method to execute the action URL.

public PageReference getMergeAndAttach() {

PageReference mergeAndAttachPage = new PageReference(getPageUrl()); ergeAndAttachPage.getParameters().putAll(getMergeAndAttachParameters());

return mergeAndAttachPage; m }

Source Listing 5.6 – getMergeAndAttach method to attach


33


With Apex interface

public PageReference mergeAndAttachPdf() { OPROARTS010.ReportEngineController reqController = new OPROARTS010.ReportEngineController(); PageReference attachPage = reqController.attachPdf(getMergeAndAttachParameters()); return attachPage; }

Source Listing 5.7 – ReportEngineController#attachPdf API


Note : To attach batch report, ‘getMergeAndAttachParameters()’ should be changed as below.

public Map<String, String> getMergeAndAttachParameters() { Map<String, String> parameterMap = new Map<String, String>(); parameterMap.put('action', 'attach'); parameterMap.put('attachmentName_1', 'UserMemo20100501a'); parameterMap.put('attachmentName_2', 'UserMemo20100501b'); parameterMap.put('attachParentId_1', getAttachParentIds()[0]); parameterMap.put('attachParentId_2', getAttachParentIds()[1]); parameterMap.put('templateControllerId_1', '00eA0000000t6Q3'); parameterMap.put('templateControllerId_2', '00eA0000000ZEu0'); parameterMap.put('targetIds_1', '00390000001j2Kw'); parameterMap.put('targetIds_2', '00390000001j2Kw, 00390000001j2Kx'); parameterMap.put('templateId', '066900000004PfH'); return parameterMap; }

Source Listing 5.8 – getMergeAndAttachParameters for batch report


34


5.3. Mail Merge and Email Operation

There are two emailing options available with RE. A) Email with targetIds parameter B) Email with emailTo parameter

A) Email with targetIds parameter

This option is used to deliver generated PDF documents to Salesforce Users, Leads and Contacts.

In this case multiple PDF documents will be generated, one each for every targetIds.

targetIds can be object Ids of any of SF User, SF Lead or SF Contact.

Recipients representing each of the targetIds will get a copy of the PDF document having merged data from the respective object.

It is possible to use Email Templates with RE email operation. These Templates will serve as the mail body/subject and can contain merge fields corresponding to SF object defined with the whatId and targetIds attributes.

When emailCc or emailBcc parameters are defined, all the mail recipients specified in these parameters will receive emails, one each for every targetIds.

Note :

E.g.: 3 targetIds, 2 emailCc addresses in the action URL A total of 9 emails will be sent by RE 1 each for 3 targetID email addresses – 1x3 =3 3 emails for the first emailCc address – 1x3 =3 3 emails for the second emailCc address – 1x3 =3

If emailTemplateId and emailSubject/emailBody parameters are used with the action URL, emailTemplateId parameter will get the precedence over emailSubject and emailBody.

B) Email with emailTo parameter This option is used to deliver generated PDF document to any out side users.

In this case a single PDF document will be generated having all the pages of mail merged data of all the targetIds.

When the emailTo parameter is used in the action URL, mail recipients belonging to the targetIds will not receive the email. Instead, the recipients specified in emailTo, emailCc and emailBcc will receive a single mail, each having the mail merged document attached to it.


35


In this case too it is possible to use Email Templates. But in this case merge fields of whatId and targetIds cannot be used.

Note :

E.g.: 3 targetIds, 1 emailTo, 2 emailCc addresses in the action URL A total of 3 emails will be sent by RE 1 email to the single emailTo address 2 emails to the two emailCc addresses In this example, all three recipients will receive the same PDF document as the mail attachment.

If emailTemplateId and emailSubject/emailBody parameters are used with the action URL, emailSubject/emailBody will get the precedence over body/subject of Email Template.

This operation is similar to emailing to targetIds, but instead of targetIds, emailTo addresses are defined.

Replace the targetIds parameter with emailTo parameter and specify the list of recipients.

Note :

Use of Email Templates with RE email operations. Email Template contains a specific format and data of the email sent by RE. It may contain mail body, mail subject and merge fields corresponding to SF object defined with the whatId and targetIds attributes.

First follow the steps a to c in section 5.1 Mail Merge and Download operation Then follow the below steps to implement this operation:

a. Name the email attachment

Provide a suitable name for the attaching document. If omitted, the PDF document will be attached with the name of the Template as the attachment name.

E.g.: AttchmentName=UserMemo20091201

b. If you are using Email Templates, identify the Email Template

It is assumed that you have already created an Email Template to use with RE.

Provide the id of the Email Template you wish to use for the emailing operation.

E.g.: emailTemplateId =00X0000000QpBV


36


Go to Setup Communication Templates Email Templates Select the appropriate Email Template and get the Id.

Figure 30 – Get email template ID

c. If you are using Email Templates, set the object Id that is related to the

Email Template

E.g.: whatId = should be the Id of the RelatedtoType object of the Email Template

whatId supports accounts, assets, campaigns, cases, contracts, opportunities, orders, products, solutions, profile and Custom Objects.


37


Figure 31 – Visualforce email template source

d. If you are not using Email Templates, set the mail subject

Use emailSubject parameter to set a suitable subject for the email. This parameter will be ignored if emailTemplateId is specified.

e. If you are not using Email Templates, set the mail body

Use emailSubject parameter to set a suitable subject for the email. This parameter will be ignored if emailTemplateId is specified.

f. Specify additional recipients

Set emialCc and emailBcc if you want to send copies of the PDF document to other recipients.

g. Specify the action

For merge and email operation the action should be specified as email.


38


Batch report email operation:

With RE its also possible to generate multiple PDF documents for multiple templateControllers, each with multiple targets and the possibility to email each document as an attachment to different recipients at once. • Specify multiple templateControllerIds Please see in section 5.2 Mail Merge and Attach. • Specify multiple targetIds Please see in section 5.2 Mail Merge and Attach.

• Specify multiple attchmentName Please see in section 5.2 Mail Merge and Attach.

How to perform this action with basic integration:

With URL interface(Using targetIds)

Edit the action URL you created for ‘Mail Merge and Download’ action by appending the necessary values for above a to g steps.

When Email Template is used:

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?action=email&display Name=OPROARTS&emailCc=&emailTemplateId=00e90000000EEWW&returnUrl=%2Fapex%2Foproarts010__reportengineabout&targetIds=00390000001j2Kw,00390000001j2Kx&templateControllerId=00e90000000IEpiAAG&templateId=06690000000L1S6AAK&whatId=00e90000000IEpiAAG

https

When Email Template is NOT used:

a) With email body and subject(whatId not needed)

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?action=email& di splayName=OPROARTS&emailCc=&returnUrl=%2Fapex%2Foproarts010__reportengineabout&targetIds=00390000001j2Kw,00390000001j2Kx&templateControllerId=00e90000000IEpiAAG&templateId=06690000000L1S6AAK&emailTemplateBody=EmailSampleBody&emailSubject=EmailSampleSubject

b) Without emailTemplateId or email body and subject(whatId not needed)

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?action=email&di splayName=OPROARTS&emailCc=&returnUrl=%2Fapex%2Foproarts010__reportengineabout&targetIds=00390000001j2Kw,00390000001j2Kx&templateControllerId=00e90000000IEpiAAG&templateId=06690000000L1S6AAK

https

https



39


Note : To email batch reports the URL should be modified as below.

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?action=email&display Name=OPROARTS&emailCc=&emailTemplateId=00e90000000EEWW&returnUrl=%2Fapex%2FOPROARTS010__reportengineabout&targetIds_1=00390000001j2Kw,00390000001j2Kx&targetIds_2=00390000001j2Kx&templateControllerId_1=00e90000000IEpiAAG&&templateControllerId_2=00e90000000IEpiAAA&templateId=06690000000L1S6AAK&whatId=00e90000000IEpiAAG

https

Figure 32 – Batch report with Email action

How to perform this action with advanced integration:

With URL interface (Using targetIds)

Add above d to g parameters to the same Map object.

public Map<String, String> getMergeAndEmailParameters() { Map<String, String> parameterMap = new Map<String, String>(); parameterMap.put('action', 'email'); parameterMap.put('displayName', userInfo.getFirstName() + ' ' + userInfo.getLastName()); parameterMap.put('emailCc', emailAddress); parameterMap.put('returnUrl', Page.reportEngineAbout.getUrl()); parameterMap.put('emailTemplateId', getEmailTemplate().Id); parameterMap.put('templateControllerId', userInfo.getProfileId()); parameterMap.put('targetIds', userInfo.getUserId()); parameterMap.put('templateId', '066900000004PfH'); parameterMap.put('whatId', userInfo.getProfileId()); return parameterMap; }

Source Listing 5.9 – getMergeAndEmailParameters to add parameters



40


public PageReference getMergeAndEmail() { PageReference mergeAndEmailPage = new PageReference(getPageUrl()); mergeAndEmailPage.getParameters().putAll(getMergeAndEmailParameters()); return mergeAndEmailPage; }

Source Listing 5.10 – getMergeAndEmail method to send email With Apex interface

public PageReference mergeAndEmailPdf() { OPROARTS010.ReportEngineController reqController = new OPROARTS010.ReportEngineController(); PageReference emPage = reqController.emailPdf(getMergeAndEmailParameters()); return emPage; }

Source Listing 5.11 – ReportEngineController#emailPdf API

public Map<String, String> getMergeAndEmailParameters() { Map<String, String> parameterMap = new Map<String, String>(); parameterMap.put('action', 'email'); parameterMap.put('displayName', userInfo.getFirstName() + ' ' + userInfo.getLastName()); parameterMap.put('emailCc', emailAddress); parameterMap.put('returnUrl', Page.reportEngineAbout.getUrl()); parameterMap.put('emailTemplateId', getEmailTemplate().Id); String[] templateControllerIds = getTemplateControllerIds(); If (templateControllerIds != null) { For (integer i = 1; i <= templateControllerIds.size(); i++ ) { parameterMap.put('templateControllerId_' + i, templateControllerIds[i-1]); parameterMap.put('targetIds_' + i, getTargetIds(templateControllerIds[i-1])); } } parameterMap.put('templateId', '066900000004PfH'); parameterMap.put('whatId', '00eA0000000sGLW'); return parameterMap; }

Source Listing 5.12 – getMergeAndEmailParameters() for Batch report


You can use emailTo parameter for above example’s ‘targetIds’ parameter. emailTo is used for to deliver generated PDF document to any outside users.


41


5.4. Mail Merge and Fax Operation

There are two faxing options available with RE. A) Fax with targetIds Parameter B) Fax with faxTo Parameter

A) Fax with targetIds Parameter

This option is used to deliver generated PDF documents to SF Users, Leads and Contacts as fax messages.

In this case multiple PDF documents will be generated, one each for every targetIds parameter. The targetIds can be object Ids of any of SF User, SF Lead or SF Contact. Recipient fax numbers representing each of the targetIds will get a copy of the PDF document having merged data from the respective object. If both emailTemplateId and emailSubject/emailBody parameters are used with the action URL., emailTemplateId parameter will get the precedence over emailSubject and emailBody.

B) Fax with faxTo Parameter

This option is used to deliver generated PDF document via fax to any out side users.

In this case a single PDF document will be generated having all the pages of mail merged data of all the targetIds. When the faxTo parameter is used in the action URL, fax recipients belonging to the targetIds will not receive the fax. Instead, the recipients specified in faxTo will receive a single fax, having the mail merged document as the fax message. In this case if both emailTemplateId and emailSubject/emailBody parameters are used with the action URL, emailSubject and emailBody parameter will get the precedence over emailTemplateId. This operation is similar to faxing to targetIds, but instead of targetIds, faxTo numbers are defined.

Replace the targetIds parameter with faxTo parameter and specify the list of recipients fax numbers.


42


Notes on Using Email Templates: Note :

1. Certain email2fax service providers require following a given syntax when specifying the email subject. Please refer the guides of respective providers for more information on setting the mail subject.

2. It is possible to use static fax cover pages by designing Email Template body. But in this case merge fields of whatId and targetIds cannot be used.( This means you can use only plain static contents with plain text Templates or static HTML formatted contents with the Custom type Templates.)

3. RE uses email2fax services to fax the PDF document. You can subscribe to any commercial emil2fax service provider to use the faxing operation.

First follow the steps a to c described in section 5.1 Mail Merge and Download operation. Then follow the below steps to implement this operation:

a) If you are using Email Templates, identify the Email Template

It is assumed that you have already created an Email Template to use with RE.

Provide the id of the Email Template you wish to use as the fax cover page.

E.g.: emailTemplateId =00X90000000QpV

Go to Setup Communication Templates Email Templates Select the Appropriate Email Template and get Id b) If you are not using Email Templates, set the mail subject

Use emailSubject parameter to set a suitable subject in the cover page of the fax message. This parameter will be ignored if emailTemplateId is specified.

c) If you are not using Email Templates, set the mail body

Use emailbody parameter to set a suitable content for the fax cover page. This parameter will be ignored if emailTemplateId is specified.

d) Specify the fax service provider

It is compulsory to define faxService parameter. E.g.: faxService={faxNumber}@fax1.com ‘fax1.com’ is the fax service provider.

e) Specify the action

For mail merge and fax operation the action should be specified as fax.


43


Batch report fax operation:

This section describes how to generate multiple PDF documents for multiple templateControllers each with multiple targets and fax each documents to different recipients at once. • Specify multiple templateControllerIds Please see in section 5.2 Mail Merge and Attach. • Specify multiple targetsIds Please see in section 5.2 Mail Merge and Attach.

• Specify multiple faxTo The syntax of faxTo parameter is changed to faxTo_x (where x = 1, 2, 3..). For example faxTo_1, faxTo_2, faxTo_3 … etc. To fax a particular report to the fax numbers ‘94112346664, 94112346668’ and another report to fax number ‘94112346656’, faxTo_x parameter is specified as follows.

faxTo_1=94112346664, 94112346668 faxTo_2=94112346656

Then the report related to the templateControllerId_1 will be send to two recipients specified in the faxTo_1 and the report related to the templateControllerId_2 will send to the recipient specified in the faxTo_2. Note : It is useless to specify faxTo_x without including templateControllerId_x (x=1, 2, 3 …).

How to perform this operation with basic integration:

With URL API

Edit the action URL you created for ‘Mail Merge and Download’ action by appending the necessary values for above a to e steps.

When Email Template is used:

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?action=fax& emailTemplateId=00e90000000EEWW&returnUrl=%2Fapex%2FOPROARTS010__reportengineabout&targetIds=00390000001j2Kw,00390000001j2Kx&templateControllerId=00e90000000IEpiAAG&templateId=06690000000L1S6AAK&faxService={faxNumber}%40fax1.com

https


44


When Email Template is NOT used:

1. With email body and subject(whatId not needed)

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?action= fax& returnUrl=%2Fapex%2FOPROARTS010__reportengineabout&targetIds=00390000001j2Kw,00390000001j2Kx&templateControllerId=00e90000000IEpiAAG&templateId=06690000000L1S6AAK&emailTemplateBody=EmailSampleBody&emailSubject=EmailSampleSubject&faxService={faxNumber}%40fax1.com

2. Without email body and subject(whatId not needed)

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?action=fax& returnUrl=%2Fapex%2FOPROARTS010__reportengineabout&targetIds=00390000001j2Kw,00390000001j2Kx&templateControllerId=00e90000000IEpiAAG&templateId=06690000000L1S6AAK&faxService={faxNumber}%40fax1.com

Create a Button or a Link for this URL and place it in a suitable page layout. Note : To fax batch reports, the URL should be modified as below.

httts ://oproarts010.ap1.visual.force.com/apex/reportEngine?action=fax&email TemplateId=00e90000000EEWW&returnUrl=%2Fapex%2Foproarts010__reportengineabout&targetIds_1=00390000001j2Kw,00390000001j2Kx&targetIds_2=00390000001j2La&templateControllerId_1=00e90000000IEpiAAG&templateControllerId_2=00e90000000IEpiAAA&templateId=06690000000L1S6AAK&faxService={faxNumber}%40fax1.com

https

https

https

Figure 33 – Batch report with Fax action


45


How to perform this operation with advanced integration: With URL API (Using targetIds)

Add above a to e parameters to the same Map object.

public Map<String, String> getMergeAndFaxParameters() { Map<String, String> parameterMap = new Map<String, String>(); parameterMap.put('action', 'fax'); parameterMap.put('emailSubject', faxSubject); parameterMap.put('emailBody', faxBody); parameterMap.put('faxServise', faxProvider); //{faxNumber}@fax1.com parameterMap.put('returnUrl', Page.reportEngineAbout.getUrl()); parameterMap.put('templateControllerId', userInfo.getProfileId()); parameterMap.put('targetIds', userInfo.getUserId()); parameterMap.put('templateId', '066900000004PfH'); return parameterMap; }

Source Listing 5.13 – getMergeAndFaxParameters to add parameters


public PageReference getMergeAndFax() { PageReference mergeAndFaxPage = new PageReference(getPageUrl()); mergeAndFaxPage.getParameters().putAll(getMergeAndFaxParameters()); return mergeAndFaxPage; }

Source Listing 5.14 – getMergeAndFax method to send Fax With Apex Interface

public PageReference mergeAndFaxPdf() { OPROARTS010.ReportEngineController reqController = new OPROARTS010.ReportEngineController(); PageReference faxPage = reqController.faxPdf(getMergeAndFaxParameters()); return faxPage; }

Source Listing 5.15 – ReportEngineController#faxPdf API


46


public Map<String, String> getMergeAndFaxParameters() { Map<String, String> parameterMap = new Map<String, String>(); parameterMap.put('action', 'fax'); parameterMap.put('emailSubject', faxSubject); parameterMap.put('emailBody', faxBody); parameterMap.put('faxServise', faxProvider); //{faxNumber}@fax1.com parameterMap.put('returnUrl', Page.reportEngineAbout.getUrl()); parameterMap.put('templateId', '066900000004PfH'); String[] templateControllerIds = getTemplateControllerIds(); If (templateControllerIds != null) { For (integer i = 1; i <= templateControllerIds.size(); i++ ) { parameterMap.put('templateControllerId_' + i, templateControllerIds[i-1]); parameterMap.put('faxTo_' + i, getFaxNumbers ()[i]); } } return parameterMap; }

Source Listing 5.16 – getMergeAndFaxParameters for batch report Source Listing 5.16 – getMergeAndFaxParameters for batch report Create a Button or a Link for this URL and place it in a suitable page layout. Create a Button or a Link for this URL and place it in a suitable page layout.

You can use faxTo parameter for above example’s ‘targetIds’ parameter. faxTo is used for to deliver generated PDF document to any outside users. You can use faxTo parameter for above example’s ‘targetIds’ parameter. faxTo is used for to deliver generated PDF document to any outside users.


47


OPRO Japan Co., Ltd.

Innovative Reporting Solutions Provider for the Enterprise.


48

oproarts designer for force · oproarts designer for force.com - report engine developer guide 1....

Documents