bsci word merge ipart overview - web viewsupport for ms word 2007, ... en-gb, en-au cultures. no...

BSCI Word Merge iPart– User Notes - iMIS 20.2.26.3109

Contents

BSCI Word Merge iPart Overview

Feature Set Highlights

Description of How iPart Works

Using the Word Merge iPart

IQA Preparation

Word Document Preparation

Basic Merge Steps

Word File Selection Panel

IQA Selection Panel

Matching Panel

Merge Panel

Overview of Run-time Options

Formatting Options

iPart Install Steps

iPart Setup & Config Settings

Error Messaging & Troubleshooting

BSCI Word Merge iPart Overview

Feature Set Highlights

Fully conforming ASI iPart. Runs in iMIS15.1 through iMIS 20.2. Use the iPart in Desktop, Staff/Web View or Public View. Support for MS Word 2007, 2010, 2013 and Open Office word processing documents. Conforms to the Office Open XML File Format specification from Microsoft which is an open, international, ECMA-376 Second Edition and ISO/IEC 29500 standard. Uses regular iMIS IQAs for all data access. Set of rich but simple run-time features for manipulating document and formatting data (create Activity record, etc..), support for en-US, en-GB, en-AU cultures. No special setup required like traditional MS Word merge documents to connect to an external data source. New job persistence feature that allows a user to re-run merge jobs to use the same Word document and IQA. Simple to use.

How iPart Works

The BSCI Word Merge iPart merges IQA data from iMIS into a standard MS Word document in a few simple steps. The default display panel is shown below.

First, be sure the IQA has the data columns you want in your merge. Then create a new or use an existing normal MS Word or Open Office document and add merge fields where you want the data to appear. Next use the iPart to select the Word document and an IQA. Then you match-up the document merge fields to IQA data columns and then merge into a new document with a few mouse clicks.

of 32

The iPart works as a series of 4 main panels that display in the sequence of: 1. select document, 2. select IQA, 3. match fields to columns, and 4. merge into a new document.

Review the install and configure documentation for this iPart for details on configuration options when installing in RiSE.

of 32

Using the Word Merge iPart

IQA Preparation

Note To create iMIS Activity records the iMIS ID number must exist in the IQA and have an alias name of ‘ID’ or ‘iMIS ID’.

Create the IQA

a. Before you begin, it’s important you understand which fields you want in your letter, and where they can be found.

i. Information about the contact can be found in the CsContact object.ii. Address information is in the CsAddress object

b. Next, create the IQA using the fields you need for your merge (see IQA documentation for information on how to create an IQA)c. If the field names seem ambiguous, put a more descriptive name in the Alias field. It’s best to omit spaces and not use special characters. The standard for field names is to capitalize the first letter of each word in the field name. For example, for Full Name use FullNamed. Check the box “Only display unique results”

of 32

Word Document Preparation

Start with a normal Word document. Do not use any of the merge features in Word that require you to connect to a data source or create the document as a merge document using a Word wizard or normal Word merge features.

Place merge fields in your document where you want them. The iPart is designed to work with merge field elements that conform to the Open XML File Format standard. These are inserted in MS Word as follows.

Put your cursor where you want the field to be placed in the document.

Select Insert Quick Parts Field

Choose ‘Merge Field’ from the list of field names.

Type a name for the merge field that you will match to columns in an IQA. The merge field names in the document do not have to match the IQA column names.

There is only one special consideration when creating merge fields, if you want to use the iMIS Full Address you must name the merge field: FullAddress

of 32

You should see the field placed in the document as below:

Save the document as a normal Word document.

Now with an IQA and a Word document ready you can perform the Word merge using the iPart.

of 32

Basic Merge Steps

Word File Selection Panel

The first step is to select the Word document to use as a template, below is the normal default iPart display panel.

Click on the ‘Browse’ button and drill out using the normal Windows file open dialog window and select the Word document to use as a template for the merge.

of 32

After selecting the Word document, click the ‘Load Word Doc’ button.

The name of the document you selected is displayed at the top of the iPart and the IQA selection panel displays.

Here you can either choose an IQA you have already used or select a new one.

If you have run a successful merge the document, the IQA even the merge fields that were mapped to IQA columns and run-time options are all saved each time you perform a successful merge allowing you to re-run any previous job.

of 32

IQA Selection Panel – Choose Saved Job

If you have previously used the iPart the IQA and document used in the previous job were saved by the iPart. To use a saved job, just choose the IQA from the list of saved IQAs using the drop-down.

Once the IQA is selected click the ‘Continue’ button.

of 32

IQA Selection Panel – Select New IQA

Click on the ‘Select IQA’ button and drill out to an IQA in iMIS.

Choose your IQA by navigating the document tree and click the ‘OK’ button.

of 32

Once the IQA is selected and the IQA name appears in the textbox click the ‘Continue’ button.

of 32

If the IQA requires parameters the panel to solicit the appropriate parameters will display.

Add the respective value and click the ‘Filter’ button.

of 32

Matching Panel

Use this panel to match up IQA columns to merge fields from the Word document. This is where you tell the iPart where to put the IQA data in the document. For each merge field on the left side pull down the drop-down list and choose an IQA column to match the data to. If no IQA column matches the merge fields then leave the drop-down blank.

When finished with the matching process, click the ‘Continue’ button.

of 32

Matching Panel - If Running Existing Job

If using an existing job the last match selections are presented to you. The columns can be re-matched or the last matches accepted.

Click the ‘Continue’ button when the merge fields are matched to the IQA columns.

of 32

Merge Panel

The merge panel displays the number of records returned by the IQA, run-time options, the merge fields that were matched, and any merge fields that will be removed because there was no matching column found in the IQA.

On the left side of the panel are the run-time options. See the section later in this document for details on how the run-time options can be used. One note about the creation of iMIS Activity records; the iMIS ID number must exist in the IQA and have an alias name of ‘ID’ or ‘iMIS ID’ for the Activity record to be created.

If you made a mistake matching the fields, you can re-run the matching portion of the process by clicking the ‘Re-Match’ button.

of 32

Click the ‘Merge’ button and the iPart will merge the IQA columns with the Word fields into a new document. When the processing is complete a dialog window will appear before the document opens.

Once Word opens the document it can be edited and saved like any other Word document. If you have more than several hundred records in your IQA it may take some time for Word to paginate through the newly spawned document depending on system resources.

of 32

Overview of Runtime Options

Remove merge fields in document if no corresponding IQA data columns exist. See list of Merge Fields Removed to the right.

If this option is set and there were unmatched document merge fields (the unmatch fields display in the 3rd column in the merge panel) those merge fields will be removed from the document. This setting is useful f you have a word document that has fields that do not exist in the IQA.

of 32

Merge only 10 records for preview

This will allow you to preview the results of a merge with just ten records rather than waiting for the entire merge to process and is useful for generating a quick preview of documents.

Remove merge fields in document if IQA data column is empty/null/no data. Default is checked.

This option is similar to the first option but will merge the data into the field if the data exists and remove the field from the document if the data doesn’t exist. Or put this way, this option will remove the merge field if the IQA field is present but has no data.

Create Activity records. The iMIS ID number must exist in the IQA and have an alias name of ‘ID’ or ‘iMIS ID’ for the Activity record to be created.

The iMIS ID does not have to appear in the document as a field bit it must be part of the IQA to produce an activity record. If this option is selected, a LETTER type Activity record will be created.

Formatting Options

Formatting data other than text can be accomplished in 3 ways:

let the iPart format the data, format the data in the IQA using a SQL Expression, use techniques in MS Word to format the data.

of 32

Formatting Method 1 – Let the iPart Format the Data

On-board part formatting options are listed here.

Date Formatting Settings

The date formatting options are listed on the merge panel or no formatting can be applied (then the time will be displayed). The formatting will be applied to all the iMIS date columns in the IQA that are used in the merge.

Without formatting this is how dates from iMIS display:

Number/Currency Formatting Settings

The only formatting of currency and numbers is the display of decimal places and the formatting is applied to all the iMIS number columns in the IQA used in the merge.

Without formatting this is how money columns from iMIS display:

of 32

Formatting Method 2 – Use a SQL Expression in Your IQA

In the IQA, choose the ‘Display’ tab. Insure the view mode is set to ‘All’.

At the bottom of the Display tab, see the section titled ‘Custom’.

of 32

Type an expression into the text box, the example above formats a date using an expression like this:

CONVERT(varchar(10), vBoCsContact.JoinDate, 101)

See ASI’s documentation on using SQL expressions for more details and examples.

of 32

iPart Install Steps

For iMIS 20.2.xx.xxx the link to the ASI Help Site reference for installing iParts is: http://docs.imis.com/20.2/#!packageinstallerutil.htm.

More details on installing BSCI iParts is here: http://www.bscichicago.com/install_bsci_iparts.shtml

To install an iPart package, save the .ipackage file to the C:\Program Files (x86)\ASI\iMIS\Net\package\pending folder (check paths on your local system). If the folders do not exist, move to the next step, which will create them for you.

Log in to the staff site and go to Settings > Utilities > Package installer.

of 32

http://docs.imis.com/20.2/#!packageinstallerutil.htm

Select the packages to install from the Show dropdown list and click Install.

Barring any permission issues you should see the iPart package install successfully.

Go to the ‘iPart Setup & Config Settings’ section below to add the iPart to a RiSE content record.

of 32

Special February 2016 Install Note

Although the 20.2.26.3109 package installer seems to work we have noticed it no longer creates the iPart content type in RiSE. We have an open SMR on this with ASI (373266). For this version of the BSCI Word Merge iPart we have prepared a .zip file with both the ipackage install file and the individual iPart components such that a manual install can occur. Here are the contents of the .zip file.

iPart Components

For a manual install place the components of the iPart into the following folders in the file system:

Main iMIS Application - Supports desktop and web-based iMIS users.

.dll - /net/bin folder, typically: C:\Program Files (x86)\ASI\iMIS\Net\bin

BSCI.iPart.MSWordMergeTool.dll (BSCI iPart library)DocumentFormat.OpenXml.dll (Office Open XML File Format library)

ASI Platform Install - Supports process automation, tasks, RiSE publishing, etc..

.dll - /application ./net/bin folder, typically: C:\AsiPlatform\Asi.Scheduler_xxxxxxxx\bin

BSCI.iPart.MSWordMergeTool.dll (BSCI iPart library)DocumentFormat.OpenXml.dll (Office Open XML File Format library)

Where XXXXXXXX is the name of your install directory name, then restart AsiScheduler by browsing to the root of the site.

.ascx - /net/iparts/custom

BSCI_MSWordMergeTool_Display.ascx (main iPart user gui)BSCI_MSWordMergeTool_Config.ascx (main iPart config gui)

of 32

Check if SQL Table for Jobs Created

If you do not see the drop-down list with saved IQAs after you run your first job, check the SQL database and insure the WMJobs table was created when you ran the install package.

If the table does not exist it is created, the script is in the /zip folder and the ipackage should create the table.

of 32

If Content Type Not Imported by Package Installer

If you do not see the BSCI Word Merge iPart listed when trying to add the iPart to a RiSE content record like in the image below, then you may have to import the content type definition manually.

To import the content type definition manually, log in to the staff site and go to Settings > Utilities > Package installer.

of 32

Click on the ‘Import’ button …

Then drill out to the BSCI_Word_Merge_iPart_CTDef.xml file in the .zip file:

Check the override checkbox and then click the ‘Import’ button.

of 32

iPart Setup & Config Settings

Add the iPart to a page in RiSE, in the page definition tab click the ‘Add content’ link.

Select the Custom folder and choose the ‘BSCI Word Merge iPart’ and click the ‘OK” button.

Note: If you do NOT see the BSCI Word Merge iPart in the Custom folder then check the section above about installing the iPart.

of 32

Set the iPart configuration properties:

Here is a description of the iPart properties used to configure the iPart for use in content.

Do Not Render In Design Mode

We generally recommend always checking this option to ON. No need to run any code while viewing the iPart in design mode.

Enable Informational Debug Output

Generally is left unchecked. It can be checked to enable verbose debugging to the Windows event Application log to assist in resolving a problem. Not necessary for normal operations.

IQA Start Folder Path

This setting allows the control that browses the IQA document tree to always start at a specific place in the tree speeding up access to IQAs. Especially useful if the iPart is intended for a specific type of letter/IQA combination. If left blank the entire IQA document tree is available in the IQA browser control.

Click ‘OK’ after filling out the property settings.

of 32

General Error Messaging & Troubleshooting

Culture Support – Date Formats

The tool supports several cultures but if yours is not supported you will see this message. Just inform BSCI and we will add support for your respective date format.

Possible IQA Name Error

If, after you select an IQA you see the error below, check the name of your IQA.

Notice the slash in the IQA name below, just change the IQA name as a work-around.

of 32

Possible Merge Field Name Error

When selecting a document if you get this error means you have duplicate merge field names in the document, merge field names must be unique.

Possible Package Install Error

You may receive a file access error when loading the iPart install package.

Insure the iMIS application pool identity has rights to the application /bin folder.

of 32

bsci word merge ipart overview - web viewsupport for ms word 2007, ... en-gb, en-au cultures. no...

Documents