Archer Multi-Record Publisher

The Archer Multi-Record Publisher is a .NET console application written in C# and intended to be run on a scheduled basis through the Windows Task Scheduler. Other automation software can be used in place of Windows Task Scheduler if desired.

The utility runs an advanced search against the module of your choice to look for records that have been marked “Merge Ready”. If it finds any records, it will inspect each one to determine the correct mail merge template to use for that record, and then perform a merge. The utility will then copy the resulting document to the configured output location. Finally, it will reset the flag to ensure that each record is only uploaded one time.

On this page

Revision notes

Document Version	Published Date	Notes
1.0	August 2020	Initial release

Overview of Archer Multi-Record Publisher

Benefits

Archer Multi-Record Publisher enables you to:

Automate the mail merge process
Allow users to trigger a mail merge simply by setting a values list

Prerequisites

Components	Recommended Software
Operating System	Windows Server 2012 R2
CPU	1 GHz or faster
RAM	512 MB or more
Disk Space	4.5 GB or more
Framework	Microsoft .Net framework 4.6 or higher
Deployment Requirements	on-premises implementations can deploy the tool on the server that is hosting the RSA Archer Platform.
Network Requirements	The Multi-Record Publisher should have network access to the Archer environment and to the output location for the merge documents.

Archer Multi-Record Publisher components

Architecture diagram

The following diagram provides a high-level overview of the data flow process for the Archer Multi-Record Publisher.

Installing and configuring Archer Multi-Record Publisher

Installation overview

This section provides instructions for configuring the Archer Multi-Record Publisher within the Archer Platform.

It is assumed that the reader has both working knowledge of all products involved, and the ability to perform the tasks outlined in this section. Administrators must have access to the documentation for all products in order to install the required components.

Important: The integration described in this guide is based on current requirements. If additional customization or enhancements are needed, please contact Archer Help for assistance.

The Multi-Record Publisher is an ASP.NET console application. The solution includes two XML configuration files. These allow for the specification of authentication credentials, along with other necessary details.

Installation and configuration

Logging

The solution makes use of a well-known logging framework called NLog. NLog allows for the creation of one or more log <target> entries, and one or more associated <logger>entries. The targets define potential “listeners” for log information, and the loggers define the rules associated with each of them, including log level. Although a sample config file is provided with the solution, a full discussion of the configuration file and its use is outside the scope of this document. For additional details, please see the NLog documentation.

Configuring Archer

The Multi-Record Publisher expects you to specify some values in a configuration file (discussed in the next section). These values will refer to fields you configure in your Archer instance. You must configure a few fields in the application containing the content records you want to merge.

Field Name	Field Type	Is Calc	Is On Layout	Description
Merge Template Field	Numeric	Yes	No	A calculated numeric field that contains the ID of a valid Mail Merge Template
Output File Name	Text	Yes	No	A calculated text field that contains the name of the output file for each individual record. A typical calculation might be CONCATENATE([Tracking Id],”.pdf”)
Is Merge Ready	Values List	Yes or No	Yes or No	A values list field that can be calculated if desired but could also be set manually. This field will be checked to determine whether a record is ready for merge. After a record is merged, the utility resets this flag to prevent multiple unattended merges of the same content. If this field is calculated, it need not be on the layout.
Attachment	Attachment	No	Yes or No	This optional field can be created and configured if it is desired for the merged document to be attached to the content record from which it came.

.NET configuration

An ASP.NET console application uses an XML configuration file in the form of the MultiRecordPublisherUtil.exe.config. This file contains the following configuration details:

<addkey="cacheFilePath"value="[cacheFilePath]"/>

<addkey="cacheFileEncryptionPassphrase"value="[EncryptionPassphrase]"/>

<addkey="securityProtocolVersion" value="[securityProtocolVersion]"/>

<addkey="useSslValidation"value="[true/false]"/>

<addkey="archerBaseUrl"value="https://[YourArcherHostURL]/archer"/>

<addkey="archerInstance"value="[InstanceName]"/>

<addkey="archerUser"value="[UserName]"/>

<addkey="archerPassword"value="[Password]"/>

<addkey="moduleGuid"value="[moduleGuid]"/>

<addkey="trackingIdFieldGuid"value="[trackingIdFieldGuid]"/>

<addkey="mergeTemplateIdFieldGuid"value="[mergeTemplateIdFieldGuid]"/>

<addkey="outputPath"value="[outputPath]"/>

<addkey="outputFileNameFieldGuid"value="[outputFileNameFieldGuid]"/>

<addkey="mergeReadyFieldGuid"value="[mergeReadyFieldGuid]"/>

<addkey="mergeReadyValuesListValue"value="[Yes Value]"/>

<addkey="notMergeReadyValuesListValue"value="[No Value]"/>

<addkey="attachMergedFile"value="[true/false]"/>

<addkey="attachmentFieldGuid"value="[attachmentFieldGuid]"/>

<addkey="searchPageSize" value="[searchPageSize]" />

<addkey="httpTimeoutMilliseconds" value="[httpTimeoutMilliseconds]"/>

</appSettings>

The following is an example of the configuration for theXML configuration code.

<addkey="cacheFilePath"value="c:\temp\"/>

<addkey="cacheFileEncryptionPassphrase"value="d0n7TryTh1s@h0m3!"/>

<addkey="securityProtocolVersion" value="Tls12"/>

<addkey="useSslValidation"value="false"/>

<addkey="archerBaseUrl"value="http://localhost/archer"/>

<addkey="archerInstance"value="Archer"/>

<addkey="archerUser"value="adminuser"/>

<addkey="archerPassword"value="Password@123"/>

<addkey="moduleGuid"value="25D34F7E-1BE6-4BE0-A2BB-1D7F98ED9493"/>

<addkey="trackingIdFieldGuid"value="762E8F78-00ED-4791-B106-364C14B26662"/>

<addkey="mergeTemplateIdFieldGuid"value="E6FEC3BF-E144-4976-A972-073908EBD09D"/>

<addkey="outputPath"value="c:\temp\mergeOutput\"/>

<addkey="outputFileNameFieldGuid"value="795C44F8-7DA4-429C-8B61-6823177BAA5E"/>

<addkey="mergeReadyFieldGuid"value="19714C4E-7D00-4560-8DF6-001816003AB5"/>

<addkey="mergeReadyValuesListValue"value="Yes"/>

<addkey="notMergeReadyValuesListValue"value="No"/>

<addkey="attachMergedFile"value="true"/>

<addkey="attachmentFieldGuid"value="0E8147C4-C070-444B-88DF-3523D0BD3C3B"/>

<addkey="searchPageSize" value="50"/>

<addkey="httpTimeoutMilliseconds" value="30000"/>

</appSettings>

The following is a description of each setting in MultiRecordPublisherUtil.exe.config file.

Setting	Description
cacheFilePath	Path to the location where the cache file will be written. This flat file is used to cache Archer ID values. When the solution is started, values are looked up from the configured Archer instance and stored in the cache file. This enables correctly referenced fields, modules, and other resources to use IDs appropriate to the Archer instance.
cacheFileEncryptionPassphrase	If provided, the cache file is encrypted using this setting as the pass phrase, providing security for data at rest.
securityProtocolVersion	This optional value dictates which security protocol should be used. Options include: SSL3, TLS 1.0, TLS 1.1, and TLS 1.2.
useSslValidation	When set to true, custom validation is used for the SSL certificate. This is necessary when using a self-signed certificate to avoid validation dialogs.
archerBaseUrl	The root URL for the Archer instance from which information is pulled.
archerInstance	The name of the Archer instance from which information is pulled.
archerUser	The name of the account used to pull information from Archer.
archerPassword	The password for the account used to pull information from Archer.
moduleGuid	The GUID for the content module containing the records you want to merge.
trackingIdFieldGuid	The GUID of the tracking ID field in the module. This field is used to inform the merge process of the content ID being merged.
mergeTemplateIdFieldGuid	The GUID of the calculated numeric field (Merge Template Field) containing the ID of the mail merge template that will be used for this content record.
outputPath	The location to which the merged documents should be written.
outputFileNameFieldGuid	The GUID of the calculated text field (Output File Name) containing the name to be used for the merged file.
mergeReadyFieldGuid	The GUID of the values list field (Is Merge Ready) that indicates whether or not a given content record is ready to be merged.
mergeReadyValuesListValue	The text of the values list value that that will indicate that a content record is ready for upload.
notMergeReadyValuesListValue	The text of the values list value that that will indicate that a content record is not ready for upload.
attachMergedFile	This setting is optional. If set to true, an attachment field must also be specified. The application will use this field as the location to attach the merged file back to the content record from which it came.
attachmentFieldGuid	The GUID of an attachment field to which the utility can attach the merged file upon completion of the merge process. This field is not needed unless the attach Merged File setting is included and set to “true”.
searchPageSize	The utility uses an advanced search to identify records ready for merge. The default page size is 50. Use this setting to change the number of records returned in each page of the search.
httpTimeoutMilliseconds	The httpTimeoutMilliseconds provides a configuration setting that enables the user to override the default HTTP timeout of 30,000 milliseconds (30 seconds). This value is in milliseconds and should be set to the number of seconds you want HTTP timeout to take * 1000.

Configuration of Multi-Record Publisher

Extract the zip file MultiRecordPublisherUtil.zipto a location/folder.
Edit the app Settings section of the XML configuration file “MultiRecordPublisherUtil.exe.config”.
1. Go to the application folder MultiRecordPublisher and locate the MultiRecordPublisherUtil.exe.config file.
2. Open MultiRecordPublisherUtil.exe.config file and provide the following information:

<addkey="cacheFilePath"value="[cacheFilePath]"/>

<addkey="cacheFileEncryptionPassphrase"value="[EncryptionPassphrase]"/>

<addkey="securityProtocolVersion" value="[securityProtocolVersion]"/>

<addkey="useSslValidation"value="[true/false]"/>

<addkey="archerBaseUrl"value="https://[YourArcherHostURL]/archer"/>

<addkey="archerInstance"value="[InstanceName]"/>

<addkey="archerUser"value="[UserName]"/>

<addkey="archerPassword"value="[Password]"/>

<addkey="moduleGuid"value="[moduleGuid]"/>

<addkey="trackingIdFieldGuid"value="[trackingIdFieldGuid]"/>

<addkey="mergeTemplateIdFieldGuid"value="[mergeTemplateIdFieldGuid]"/>

<addkey="outputPath"value="[outputPath]"/>

<addkey="outputFileNameFieldGuid"value="[outputFileNameFieldGuid]"/>

<addkey="mergeReadyFieldGuid"value="[mergeReadyFieldGuid]"/>

<addkey="mergeReadyValuesListValue"value="[Yes Value]"/>

<addkey="notMergeReadyValuesListValue"value="[No Value]"/>

<addkey="attachMergedFile"value="[true/false]"/>

<addkey="attachmentFieldGuid"value="[attachmentFieldGuid]"/>

<addkey="searchPageSize" value="[searchPageSize]"/>

<addkey="httpTimeoutMilliseconds" value="[httpTimeoutMilliseconds]"/>

</appSettings>

The following table provides a description of each setting.

Setting	Description and Example
[cacheFilePath]	Cache file path Example: c:\temp\
[EncryptionPassphrase]	Encryption pass phrase Example: d0n7TryTh1s@h0m3!
[Ssl3/Tls/Tls11/Tls12]	The version of security protocol to be used in communicating with the Archer web server Example: Tls12
[true/false]	True or false to validate SSL Example: false
[YourArcherHostURL]	Archer host URL Example: company.com or 10.20.30.40:99
[InstanceName]	Instance name of your Archer environment Example: ArcherProd Note: Instance name is case sensitive.
[UserName]	Username of the account Example: adminuser
[Password]	Password of the user account Example: Password@123
[moduleGuid]	GUID of the module Example: 25D34F7E-1BE6-4BE0-A2BB-1D7F98ED9493
[trackingIdFieldGuid]	The GUID of the tracking ID field Example: 762E8F78-00ED-4791-B106-364C14B26662
[mergeTemplateIdFieldGuid]	The GUID of the field that contains the calculated merge template id. Example: E6FEC3BF-E144-4976-A972-073908EBD09D Example: B4EF91C4-B85C-4A91-9738-73AF958F5813
[outputPath]	A location on the filesystem Example: C:\temp\mergeoutput\
[outputFileNameFieldGuid]	The GUID of the field that contains the calculated file name to be used for the merge output of each individual record. Example: 795C44F8-7DA4-429C-8B61-6823177BAA5E
[mergeReadyFieldGuid]	The GUID of the values list field that is used to flag content records as “ready for merge” Example: EFCF320E-D3C4-44AD-B1A9-3C486A9EA5C7
[mergeReadyValuesListValue]	The text of the values list value that means a record is ready for merge Example: Yes
[notMergeReadyValuesListValue]	The text of the values list value that means a record as not “ready for merge” Example: No
[searchPageSize]	searchPageSize Example: 50
[httpTimeoutMilliseconds]	httpTimeoutMilliseconds Example: 30000

Save and Close the MultiRecordPublisherUtil.exe.config file.

Note: Changing the Archer URL in the Config file requires the deletion of the previously used cache file.

Open NLog.config. Go to the application folder MultiRecordPublisher and locate file target and provide the following information.

filename="[logFilePath]"

Example: fileName="c:\temp\MultiRecordPublisherUtil.log"

Name of the file to write to. Provide name of the file to write to with the full path.

archiveFileName="[archivelogFilePath]"

Example: archiveFileName="c:\temp\logArchive\MultiRecordPublisherUtil.{#}.log"

Name of the file to be used for an archive. It contains a special placeholder {#} that will be replaced with a sequence of numbers depending on the archiving strategy. The number of hash characters used determines the number of numerical digits to be used for numbering files.
Open Windows Task Scheduler and create a task to run MultiRecordPublisherUtil.exe according to the desired schedule. Create a unique Archer user account for the task so that no other process can authenticate with the same credentials and invalidate the session being used by your task.

To create a Windows Scheduler Task for the application:

Open Windows Task Scheduler.
Click Create Task.
In the dialog, enter the following:

Section	Description
General	Provide a Name that identifies the Multi-Record Publisher process
Triggers	Create a new trigger by providing the Frequency to run the tool
Actions	Select the MultiRecordPublisherUtil.exe from extracted application folder MultiRecordPublisher. (Optional): Select a config file in “Add arguments” if you need to schedule multiple tasks

Section

Description

General

Provide a Name that identifies the Multi-Record Publisher process

Triggers

Create a new trigger by providing the Frequency to run the tool

Actions

Select the MultiRecordPublisherUtil.exe from extracted application folder MultiRecordPublisher.

(Optional): Select a config file in “Add arguments” if you need to schedule multiple tasks

Once all the properties for windows task schedule is complete, click OK.

Configuration of multiple tasks (Optional)

The utility is designed to run multiple instances from a single installation by passing different config files on the command line. This would allow for different applications, or even different Archer instances to be targeted. In order to run the utility with a config file other than the default (.exe.config), you must pass that config file as a command-line argument to the utility. For example: Multirecordpublisherutil.exe myConfigFile.config

Test the connection

A successful process displays the following message in the MultiRecordPublisherUtil.log:

Security

Initially the configuration values should be entered in app Settings section and saved. When the utility runs, app Settings section text values will be encrypted as shown below. If changes are desired, the app Settings section can be replaced with a new plain text version containing the updated values, which will be encrypted on the next execution.

Security considerations

Use HTTPS or TLS for secured connection between the Multi-Record Publisher and Archer.
Run the Multi-Record Publisher with the least-privileged account (Logon Service permission).

Execution

Execute the utility MultiRecordPublisherUtil.exe at least once after the configuration is completed.

Risk considerations

The Multi-Record Publisher must be executed immediately after configuring. Failure to do so will result in a risk exposure, leaving parameters entered in app Settings (includes Archer credentials) in the config file in plain text.

Troubleshooting

Configuration file (MultiRecordPublisherUtil.exe.config)

Ensure the values in the configuration file match your Archer environment.
Do not include default.aspx in the Archer URL.
The Archer instance name is case sensitive.
If you are changing the Archer URL in the config file, ensure that you have deleted the previously used cache file.
Ensure that dedicated, active Archer user account credentials are used in the configuration file.
Ensure the Values List of the field ‘Is Merge Ready’ in Archer matches the text values used in the Config file appSettings section for ‘mergeReadyValuesListValue’ and ‘notMergeReadyValuesListValue’.

Archer environment

Ensure the numeric value in the field ‘Merge Template Field’ matches the ‘ID’ of Mail Merge Template (Administration -> Management Reporting -> Mail Merge Templates).
If the field ‘Is Merge Ready’ is a calculated field, the Utility will not update (reset the value) the field.