Archer Multi-Record Publisher

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.

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.

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:

<appSettings>

<add key="useSoapAuth" value="[true/false]" /><addkey="cacheFilePath"value="[cacheFilePath]"/>

<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]"/>

<add key="outputMergedFilesToDisk" value="[true/false]" />

<add key="encryptFileOnDisk" value="[true/false]" />

<add key="outputFileEncryptionPassphrase" value="[EncryptionPassphrase]" />

<add key="useDefaultCredentials" value="false" />

</appSettings>

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

<appSettings>

<add key="useSoapAuth" value="false" /><addkey="cacheFilePath"value="c:\temp\"/>

<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"/>

<add key="outputMergedFilesToDisk" value="true" />

<add key="encryptFileOnDisk" value="false" />

<add key="outputFileEncryptionPassphrase" value="d0n7TryTh1s@h0m3!" />

<add key="useDefaultCredentials" value="false" />

</appSettings>

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

<appSettings>

<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
useSoapAuth	This option determines whether to use REST/SOAP api for authentication. Default value is false. If SSO is enabled with manual bypass disabled, then set this value to true.
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.
outputMergedFilesToDisk	This parameter determines to store merged files to disk.
encryptFileOnDisk	This parameter determines if output files to be encrypted.
outputFileEncryptionPassphrase	If provided, the output file is encrypted using this setting as the pass phrase, providing security for data at rest.
useDefaultCredentials	For this application, the value can safely be set to false.When true, the logged-in user’s credentials can be requested by IIS, if needed.

1. Extract the zip file MultiRecordPublisherUtil.zipto a location/folder.

2. 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:

<appSettings>

<add key="useSoapAuth" value="[true/false]" /><addkey="cacheFilePath"value="[cacheFilePath]"/>

<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]"/>

<add key="outputMergedFilesToDisk" value="[true/false]" />

<add key="encryptFileOnDisk" value="[true/false]" />

<add key="outputFileEncryptionPassphrase" value="[EncryptionPassphrase]" />

<add key="useDefaultCredentials" value="false" />

</appSettings>

 The following table provides a description of each setting.

Setting	Description and Example
[true/false]	True or false to use SOAP Authentication Example: false
[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
[true/false[	Output merged files to disk Example: true
[Encryption Passphrase]	Encryption Passphrase Example: d0n7TryTh1s@h0m3!

3. 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.

4. 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.

5. 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:

1. Open Windows Task Scheduler.

2. Click Create Task.

3. 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

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

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

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.

1. Use HTTPS or TLS for secured connection between the Multi-Record Publisher and Archer.

2. Run the Multi-Record Publisher with the least-privileged account (Logon Service permission).

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

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.

1. Ensure the values in the configuration file match your Archer environment.

2. Do not include default.aspx in the Archer URL.

3. The Archer instance name is case sensitive.

4. If you are changing the Archer URL in the config file, ensure that you have deleted the previously used cache file.

5. Ensure that dedicated, active Archer user account credentials are used in the configuration file.

6. 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’.