Excel4apps Reports Distribution Manager User Guide...
Transcript of Excel4apps Reports Distribution Manager User Guide...
version 4.17 [email protected] | www.excel4apps.com/sap Page 2 of 15
Table of Contents
1 System Requirements ................................................................................................. 4
2 Installation and Overview ............................................................................................ 4
2.1 Definitions ................................................................................................................ 4
2.1.1 Report Distribution Manager ............................................................................. 4
2.1.2 Report Distribution Row .................................................................................... 4
2.1.3 Report Distribution Row Elements .................................................................... 4
Status (Automatic) ......................................................................................................... 4
Template Directory (User Defined – Required)............................................................... 5
Source Workbook (User Defined – Required) ................................................................ 5
Save As (User Defined – Required) ............................................................................... 6
Parameters and Values 1-10 (User Defined – Optional) ................................................. 6
Suppress Zeros (User Defined – Optional) ..................................................................... 6
Format (User Defined – Required) ................................................................................. 6
Excel Format (User Defined – Required)........................................................................ 6
Workbook (User Defined – Required) ............................................................................ 6
Internal Reference (User Defined – Optional) ................................................................ 6
Working Folder (User Defined – Required) .................................................................... 6
Distribution Folder (User Defined – Optional) ................................................................. 7
Email Distribution (User Defined – Optional) .................................................................. 7
CC (User Defined – Optional) ........................................................................................ 7
BCC (User Defined – Optional) ...................................................................................... 7
Email Subject (User Defined – Optional) ........................................................................ 7
Email Comments (User Defined – Optional) ................................................................... 7
3 The RDM Toolbar ......................................................................................................... 7
4 RDM Wizard Form ........................................................................................................ 8
Clicking on the Define Row button opens the Report Definition Wizard which provides a
user interface for users to enter distribution line items in the RDM Template. .................... 8
.......................................................................................................................................... 8
4.1.1 Report Master ................................................................................................... 8
4.1.2 Report Parameters ........................................................................................... 8
4.1.3 Report Distribution ............................................................................................ 8
4.1.4 Distributed Report Name .................................................................................. 8
4.1.5 Format .............................................................................................................. 8
4.1.6 Working Folder ................................................................................................. 9
4.1.7 Distribution Folder ............................................................................................ 9
4.2 Email Selector Wizard .............................................................................................. 9
version 4.17 [email protected] | www.excel4apps.com/sap Page 3 of 15
5 User Options Form .................................................................................................... 10
5.1.1 Email Address ................................................................................................ 10
5.1.2 SMTP Server .................................................................................................. 10
5.1.3 SMTP Port ...................................................................................................... 10
5.1.4 User Name ..................................................................................................... 10
5.1.5 User Password ............................................................................................... 10
5.1.6 Active Directory Server ................................................................................... 10
5.1.7 Active Directory User Name ........................................................................... 10
5.1.8 Active Directory Password .............................................................................. 10
5.1.9 Maximum Timeout .......................................................................................... 10
6 Execute Range and Execute Sheet Form ................................................................. 11
6.1 Execute Range....................................................................................................... 11
6.2 Execute Sheet ........................................................................................................ 12
6.3 Execute Error Rows Only ....................................................................................... 12
7 Executing and Distributing Reports ......................................................................... 12
7.1 RDM Protocol ......................................................................................................... 12
7.2 Errors Causes ........................................................................................................ 12
7.2.1 Not Logged onto the Excel4apps Connector (SAP) ........................................ 12
7.2.2 Workbook, Worksheet or Named Range is protected or locked ...................... 12
7.2.3 SAP server is down or unresponsive .............................................................. 12
7.2.4 Incorrect Email Setup ..................................................................................... 12
8 Appendix A - Troubleshooting installation problems ............................................. 13
9 Release Notes ............................................................................................................ 14
9.1.1 Release 4.17 .................................................................................................. 14
9.1.2 Release 4.12 .................................................................................................. 14
9.1.3 Release 4.06 .................................................................................................. 14
9.1.4 Release 1.55 .................................................................................................. 14
9.1.5 Release 1.54 .................................................................................................. 14
9.1.6 Release 1.53 .................................................................................................. 15
version 4.17 [email protected] | www.excel4apps.com/sap Page 4 of 15
1 System Requirements
Component Requirements
Computer and Processor 1000 MHz or faster processor
Memory 2 GB
Operating System Windows XP, Vista, 7, 8 (32/64 bit)
Office 2007 SP3, 2010 SP1, 2013, .NET Programmability
.NET Framework 4.0 CP
VSTO Tools VSTO 2010 Runtime
Excel4apps Wands v3.30 or higher
2 Installation and Overview
The RDM “Report Distribution Manager” (SAP) is an Excel 2007 (or later) add-in that works
in conjunction with the Excel4apps Wand (SAP) products. It enables the user to define which
reports will be executed and with which parameter values. These reports are then
automatically distributed to end users by email or by saving in a folder location. The reports
can be in PDF format, with original formulae or in a Snapshot format.
2.1 Definitions
2.1.1 Report Distribution Manager
The Report Distribution Manager (RDM) is the Excel add-in that enables the user to prepare
a spreadsheet template containing a list of rows each of which defines a Report Distribution.
2.1.2 Report Distribution Row
A Report Distribution Row contains a file address to a source Excel template and other
report distribution definitions. The source template may contain GL Wand (SAP) Formulae
and other user formatting that the user will want to retain in any distribution to end users.
The RDM also provides the ability to modify up to 10 user-defined named ranges and their
values which the RDM will then update as part of its execution routine prior to distribution to
end users.
2.1.3 Report Distribution Row Elements
Status (Automatic)
The Status field is the error log of RDM and is updated when an RDM batch is executed.
This field lets users know which reports were executed and distributed correctly and which
distributions may have failed - and the reason for their failure. Users do not need to provide
information in this field. Any values contained in this field will be over-written at execution.
version 4.17 [email protected] | www.excel4apps.com/sap Page 5 of 15
The possible distribution failures are:
1. Timeout Waiting for Refresh The connection to SAP may not refresh formulae contained in the template
prior to the user defined timeout period. The reasons for this could be many
including loss of network connection or non-responsive SAP server.
2. Report File Save Error RDM was not able to save the open workbook to the local directory. Reasons
may include directory access restrictions or file conversion errors. If you
previously executed the row the email system may still be busy with the file.
3. Report Export to PDF Error RDM was not able to export the workbook to PDF format. . If you previously
executed the row the email system may still be busy with the file.
4. Local Directory Does Not Exist RDM was unable to access or locate the local folder to save reports.
5. Report Save to Distribution Folder Error RDM was unable to access and save the Excel formatted report to the user
selected distribution folder. If you previously executed the row the email
system may still be busy with the file.
6. Report PDF Save to Distribution Folder Error RDM was unable to access and save the PDF formatted report to the user
selected distribution folder. If you previously executed the row the email
system may still be busy with the file.
7. Company Code not selected at logon When logging on to SAP with the Excel4apps Connector, one of the company
codes required in the distribution was not selected.
Template Directory (User Defined – Required)
The Template Directory contains the directory location of the Source Workbook. This
information is required by the user and must be a valid accessible directory containing the
Distribution Source Workbook in order for the distribution to be successful.
Source Workbook (User Defined – Required)
The Source Workbook is the Excel file that RDM opens, manipulates, saves then distributes
to end users based on the report definitions provided by the user. The Source Workbook is
not saved to the Template Directory so any changes RDM makes are not persisted for the
next batch run. Changes made by the RDM during execution are saved to the user selected
Local Directory prior to distribution to end users.
version 4.17 [email protected] | www.excel4apps.com/sap Page 6 of 15
Save As (User Defined – Required)
RDM will save the Source Workbook to the local folder in the user selected Excel format.
Choices are:
1. 2010 This is the default option. RDM will save the distributed workbook in 2007-
2010 format (.xlsx) to the Local Folder.
2. 2003 Users have the option of selecting the Excel 2003 format so that RDM will
save the distributed workbook in (.xls) to the Local Folder.
Parameters and Values 1-10 (User Defined – Optional)
Users have the option to define up to 10 Named Ranges within the Source Workbook and
assign those ranges with new values in the RDM Template. RDM will then update the values
in the Named Ranges as it executes the reports.
Suppress Zeros (User Defined – Optional)
Users have the option to define a Named Range of cells, usually a long list of values, that
RDM hides rows where the returned value is zero in every cell of that row.
Format (User Defined – Required)
Defines the format that the report is to be distributed in. Choices are: PDF and/or Excel
and/or MHTML. Must be one or both but cannot be blank.
Excel Format (User Defined – Required)
Reports can be distributed to clients in one of the following 2 Excel formats:
1. Snapshot RDM will replace all the Wand (SAP) formulae with the final calculated values
prior to saving and distributing to end users.
2. Formulae RDM will preserve the Wand (SAP) formulae when saving to the distribution
workbook.
This setting only effects the Excel distribution and has no effect on the PDF distribution. All
PDF distributions will contain calculated values.
Workbook (User Defined – Required)
The Workbook field is the name of the distribution file that is sent to end users. No file
extension is required. RDM will automatically append the correct file extension (.xls, .xlsx,
.pdf) based on the Format and Save As fields when saving the file to the local directory and
prior to distributing to end users.
Internal Reference (User Defined – Optional)
The Internal Reference field is provided so that users can add comments within the
distribution. The field is completely optional and RDM does not use it when executing a
distribution.
Working Folder (User Defined – Required)
Upon execution, RDM will save all files to the user-selected Working Folder first then
distribute to the end users based on the user-defined distribution pattern – email, distribution
folder.
version 4.17 [email protected] | www.excel4apps.com/sap Page 7 of 15
Distribution Folder (User Defined – Optional)
RDM can copy files from the Working Folder to the Distribution Folder for end users to
access through a network directory or ftp or some other access method.
Email Distribution (User Defined – Optional)
The Email Distribution field is the primary email distribution list for the files. An email will be
sent to these addresses along with the attached files. This line is required if a user wishes to
distribute a report by email and they can also specify CC and BCC email addresses.
CC (User Defined – Optional)
The CC field defines the CC or “Carbon Copy” list of users to receive the report. This field is
only relevant if the primary Email Distribution field is specified. If the Email Distribution list is
blank then the CC field is ignored.
BCC (User Defined – Optional)
The BCC field defines the BCC or “Blind Carbon Copy” list of users to receive the report.
This field is only relevant if the primary Email Distribution field is specified. If the Email
Distribution list is blank then the BCC field is ignored.
Email Subject (User Defined – Optional)
The Email Subject field corresponds to the email subject line of the distribution email.
Email Comments (User Defined – Optional)
The Email Comment field corresponds to the email comments line of the distribution email.
3 The RDM Toolbar
The RDM distribution process is started by clicking on the Create Template button on a
blank Excel worksheet. This will build the initial RDM template.
Note: Only one template can be used per workbook.
version 4.17 [email protected] | www.excel4apps.com/sap Page 8 of 15
4 RDM Wizard Form
Clicking on the Define Row button opens the Report Definition Wizard which provides a user
interface for users to enter distribution line items in the RDM Template.
4.1.1 Report Master
The user selects a template workbook that they wish to distribute. The file is opened and
then the wizard automatically reads the Named Ranges from the workbook and displays
them in the Report Parameters grid.
4.1.2 Report Parameters
In the Report Parameters grid, the user is then able to map the Named Ranges to
Parameters in the RDM template.
4.1.3 Report Distribution
This group defines the email parameters associated with a distribution
4.1.4 Distributed Report Name
The Distributed Report Name is the base name for the distribution. The RDM will append the
file extension based on the distribution format required. The Excel dropdown box defines the
distributed Excel version.
4.1.5 Format
The Format Group defines the distribution file type that end users receive. The user can
select to have distributions in PDF, Excel and/or MHTML file format.
version 4.17 [email protected] | www.excel4apps.com/sap Page 9 of 15
4.1.6 Working Folder
The working folder is where the RDM saves files prior to distribution to end users.
4.1.7 Distribution Folder
The distribution folder is where end users can access reports remotely such as a network
accessible folder located via ftp, http or shared drive.
4.2 Email Selector Wizard
The select email wizard uses the Active Directory Credentials supplied in the User Options
Dialog to query the accounts on the users Domain. A list of all email address associated with
the Domain is returned in the Email List box on the left for the user to select for distribution.
The user can see email accounts added to the distribution list as they click the “Add” button.
The user can also filter emails by entering text below the Email List header.
version 4.17 [email protected] | www.excel4apps.com/sap Page 10 of 15
5 User Options Form
Properties used by the RDM to distribute reports by email and query Active Directory for
user names and email addresses are set in the User Options dialog box.
5.1.1 Email Address
The Email Address represents
the originating email address
of the reports distributed by the
RDM. This address appears in
the From property of an email
distribution message.
5.1.2 SMTP Server
The domain, or IP-address, of
an SMTP enabled mail server.
5.1.3 SMTP Port
The port the SMTP server
sends messages on. Default is
25.
5.1.4 User Name
User Name field if SMTP
server requires authentication.
5.1.5 User Password
Password field if SMTP server
requires authentication.
5.1.6 Active Directory
Server
Active Directory server that
user is connected to.
5.1.7 Active Directory User
Name
Active Directory user name
associated with the user
account.
5.1.8 Active Directory Password
Active Directory password associated with the user account.
5.1.9 Maximum Timeout
Maximum number of seconds RDM waits for a refresh from the Wand products.
version 4.17 [email protected] | www.excel4apps.com/sap Page 11 of 15
6 Execute Range and Execute Sheet Form
6.1 Execute Range
The user can execute a list of rows, or a single row selected from the RDM Template.
version 4.17 [email protected] | www.excel4apps.com/sap Page 12 of 15
6.2 Execute Sheet
The user executes all rows from an RDM Template.
6.3 Execute Error Rows Only
The user has the option to execute a list of rows that failed a previous distribution batch.
7 Executing and Distributing Reports
7.1 RDM Protocol
When reports are executed RDM follows the following protocol:
1. Opens the Template from the source directory
2. Save the updated values in the worksheets
3. Waits for the Wand products to refresh the data
4. Save the updated Template to the working folder as Target Report Name
5. Distribute reports to distribution directory, and by email, as selected
6. Logs execution errors to the Status Field
7.2 Errors Causes
Execution errors are logged in the Status field of the RDM Template. There are several other
reasons why a user might receive a logged error or an unexpected result after execution:
7.2.1 Not Logged onto the Excel4apps Connector (SAP)
If the user is not logged onto the Excel4apps Connector (SAP), any workbook that contains
a Wand (SAP) function will display an error message (glwError). RDM will pass over this
workbook and log the distribution attempt as a Connection Timeout error.
7.2.2 Workbook, Worksheet or Named Range is protected or locked
If the workbook, worksheet or named range within a sheet is protected or locked, any named
range parameters the user tries to update will be unsuccessful. This will not register as a
logged error, so users will need to ensure that the template is not protected and named
range cells are not locked from updating.
7.2.3 SAP server is down or unresponsive
After logging into the Excel4apps Connector (SAP), a sheet may still be unable to be
refreshed because of an unresponsive SAP server. This may be because of connection
reset, network error or other error in how Excel communicates with SAP. This will be logged
in the Status field as a Connection Timeout error.
7.2.4 Incorrect Email Setup
Users should test their email settings prior to attempting to execute reports. After entering
the email settings, click on the “Test Email” button. The user should receive an email
message demonstrating that the RDM email distribution has been configured correctly.
Please refer to documentation provided by your email provider for information required to set
up email.
version 4.17 [email protected] | www.excel4apps.com/sap Page 13 of 15
8 Appendix A - Troubleshooting installation problems
Depending on the version of Excel that you are using, in certain circumstances, the RDM
add-in tab may not display after you have run the Excel4apps Wands installer and have
started up Excel. Below are steps that will assist with getting the RDM tab activated.
It is important to remember that the RDM is only supported from Excel 2007 onwards and you need to be an Administrator on your PC when installing the Excel4apps Wands software. For Excel 2007, SP3 is required and for Excel 2010 SP1 is required.
1. Ensure the RDM was chosen for installation. The RDM is installed when the Complete option or when specifically selected under the Custom option in the Excel4apps Wands installer. If you originally chose the Typical installation, then only GL Wand would have been installed. You are able to re-run the installer and select Modify to choose the RDM for installation.
2. If you have already selected the RDM for installation and the RDM tab is still not visible then re-run the installer and select the Repair option to see if that resolves the issue.
3. Confirm the pre-requisites exist on your PC.
a. Under Add/Remove programs, you should find an entry for the Microsoft .Net Framework 4 Client Profile. If you see a different Microsoft .Net Framework 4 entry then you probably have the full .Net 4 framework version installed which will qualify.
b. For Excel 2007, the Microsoft Visual Studio Tools for Office Runtime should also be visible under Add/Remove programs. If your operating system is 64 bit then it will have an (x64) after the name otherwise it will show (x86). Excel 2010 SP1 automatically includes the VSTO tools for office runtime, so if you are using Excel 2010 you will not see an entry in Add/Remove programs for this pre-requisite.
4. Ensure the RDM add-in has not been deactivated in Excel. a. In Excel, go to File/Office Button->Excel Options->Add-Ins->Manage Disabled
Items-> Go. If the RDM add-in is listed as a disabled item then re-enable it. b. In Excel, go to File/Office Button->Excel Options->Add-Ins->Manage COM
Add-ins-> Go. Make sure the RDM add-in is ticked here and that the Load Behavior shows Load at Startup.
c. Restart Excel if you needed to activate the add-in at either of these locations.
5. If the previous steps have not solved the issue then setting an environment variable can provide further information as to the cause of the problem. Right click on Computer and select properties. Click Advanced system settings. Click the Environment Variables button. Under System variables, click the New button. Populate the Variable name with VSTO_SUPPRESSDISPLAYALERTS. Populate the Variable value with 0 and click OK. If the RDM add-in was activated as per step 4, then when you restart Excel, a more detailed error should be displayed about the problem. You can provide that information via email to [email protected] for further assistance.
version 4.17 [email protected] | www.excel4apps.com/sap Page 14 of 15
9 Release Notes
9.1.1 Release 4.17
Feature Description Benefit
Output Options Excel workbook being created when
not selecting this option and not emailing
Bug Fix
9.1.2 Release 4.12
Feature Description Benefit
GL Wand integration
Ignore GL Wand created named ranges when defining a report row
Enhancement
9.1.3 Release 4.06
Feature Description Benefit
Reports Wand integration
RDM integrated with Reports Wand for reports with balances only
Enhancement
Format Group MHTML output option added Enhancement
Define Row No value for parameter in report
causing the define row process to not recognize the named range.
Bug Fix
9.1.4 Release 1.55
Feature Description Benefit
User Settings Improved user setting management. Enhancement
9.1.5 Release 1.54
Feature Description Benefit
Mixed Formatting Named ranges not appearing when defining row in RDM template as a
result of mixed formatted cells. Bug Fix
Calculation
RDM not waiting for update of functions that have additional
operators applied to them resulting in an Excel error e.g. #Value and the
integer value of the error was returned.
Bug Fix
version 4.17 [email protected] | www.excel4apps.com/sap Page 15 of 15
9.1.6 Release 1.53
Feature Description Benefit
Email Email pattern check failing on
numeric after @. Bug Fix