Setup the Salentica Advent Connector for Data Broker

Sep 20, 2022

Before you Begin

Salentica should have provided the following artifacts:

This setup guide
The Connector installer package (Salentica.Advent.Connector.x.x.x.x.msi)
An SSL encryption certificate
- Submit a Support ticket for the certificate to be created
The password used to import the certificate
A configuration file specific to your deployment (Salentica.Advent.Connector.exe.config) will be necessary if a reinstall is being performed. On initial installation, the configuration is included in the Connector Installed package

**Note that the items in red above contain sensitive security information. It is critical that they be treated accordingly, and transferred and stored securely.

Please copy all of these artifacts to the machine where the software will be installed. Post-installation they can be removed if needed.

1. Install the Connector Software

Perform this step on the identified server or workstation where the Advent Client Tools are installed, while logged in as a member of the Local Administrators group.

a. As noted in the previous section, you should have copied all the provided software and artifacts to the target machine. Browse to that local location and double-click the Salentica.Advent.Connector.x.x.x.x.msi installer package (this is the only .msi file you will have been provided).

b. On the Welcome screen, click Next to continue.

c. On the Select Installation Folder screen, you can accept the default folder location, or browse to select the preferred installation location. In either case, note the location, as you will need to reference it in the next step. Ensure that the "Everyone" option is selected and click Next to continue.

d. Click Next to install the package.

e. Click Close to complete and close the installation wizard.

2. Update the Configuration File

Perform this step on the identified server or workstation where the Advent Client Tools are installed, while logged in as a member of the Local Administrators group.

a. In the previous step, you installed the application files to a target folder. Using Windows Explorer, browse to that folder location so that you can view the contents.

b. You must replace the Salentica.Advent.Connector.exe.connfig file with the sile of the same name that was provided to you by Salentica. This file contains specific information that identifies your firm to Salentica, and is how Salentica identifies which CRM database to push your Advent data info.

ASR is short for AdvScriptRunner, so that is where the AdvScriptRunner.exe is located. APXRepLocation should be where the \rep folder is located, and where we copy the .rep file into.

If using the UNC Path for the APXRepLocation causes any errors during testing or Go Live of the Advent connector, change the path to the local drive file path (ex: "C:\Program Files(x86)\APX\APXSystem\rep\")

Copy the Salentica.Advent.Connector.exe.config file provided by Salentica into the target folder above. When prompted, elect to "Replace the file in the destination."

c. Based on the install (Axys or APX) the following lines of code will need to be updated.

AXYS Install:

Line 7: OrganizationEnrollmentID - (Inside the Plugin Secure Configreation.xml.txt file from Dev Team)

Line 11: CertThumbPrint - (Inside the Plugin Secure Configreation.xml.txt file from Dev Team)

APX Install:

Line 7: OrganizationEnrollmentID - (Inside the Plugin Secure Configreation.xml.txt file from Dev Team)

Line 11: CertThumbPrint - (Inside the Plugin Secure Configreation.xml.txt file from Dev Team)

Line 12: isAPX -set value to "true"

Line 14: APXRepLocation -Retrieve from Client. This will be where all of the .rep files are stored. Use either the UNC Path or the Local Path to the subfolder location of the .rep files (ex: "C:\Program Files(x86)\APX\APXSystem\rep\"). Please ensure the "\" is included at the end of that address and inside the close parentheses.

Line 15: APXURL - Retrieve from Client. This is the browser URL that the client uses to login to the APXAPP.

Other lines of code that may or may not need to be adjusted:

8 -ArchiveAgeinDays --No update unless something was done custom

9 - DatBrokerUrl - Correct as is

10 - isDev - Correct as is

13 - ASRLocation -No update unless something was done custom

3. Import the Automation Files (APX ONLY, Go to Step 4 for Axys Install)

Perform this step on the identified server or workstation where the Advent Client Tools are installed, while logged in as a member of the Local Administrators group.

a. In the previous step, you installed the application files to a target folder. Using Windows Explorer, browse to that folder location so that you can view the contents. Inside the target folder, there should be a ReportFiles folder.

b. Drill into that folder and you should see 3 files.

c. Using your favorite editor, you will need to open and edit the salcar.mac file. Make the two changes shown below, to replace the {REPORTDATE} slug with the {last} slug, and the {OUTPUTPATH} slug with the actual location as shown below:

On the OUTPUTPATH make sure to not include the curly brackets ‘{}’ when defining the Output Path.

d. Save your file when done

e. Next you will need to import the .mac and the .scr file into APX. From the Windows Start menu, expand the Advent folder, and launch the Import Export Utility (IMEX). Click the Import Advent format button (second one in, with the 'A' on it).

f. Import each file using the following settings:

Setting	salcar.mac file	salcar.scr file
Files	InstallationTarget\ReportFiles\salcar.mac	InstallationTarget\ReportFiles\salcar.scr
Import Folder	\uncpathToAPXshare\APX$\imp\|\uncpathToAPXshare\APX$\imp\|	N/A
Import Operation	Replace matching records and append non-matching records	Replace matching records and append non-matching records
Format	Tab Delimited	Tab Delimited
Column Set	APX	APX

g. Close the IMEX utility.

Now, in APX, we need to set the security on the Script so that it can be executed by whichever user the automation will run as.

h. In APX, from the Tools menu, select Automation > Scripts.

i. Search for the "salcar" script in the list. Change the 'Owned by' to be either a specific user (who will run the automation), or to be 'everyone'.

4. Import the SSL Certificate

Perform this step on the identified server or workstation where the Advent Client Tools are installed, while logged in as a member of the Local Administrators group

a. Click the Start button and type "Run" (without the quotes) and hit enter. You should get the Run dialog.

b. In the Open box, type mmc and click ok. This will launch the Microsoft Management Console.

c. Within the MMC console, click File > Add/Remove Snap-in…

d. Your list of Available Snap-ins may differ, but you should see 'Certificates' in the list. Select Certificates, and click the Add button in the middle of the screen.

e. When prompted, choose the 'Computer account' option, and then click Next.

f. When prompted, choose the 'Local Computer' option, and then click Finish.

g. Your 'Selected Snap-ins' list should look like this. Click OK.

h. Now, back in the MMC console, drill to expand into Certificates (Local Computer) > Personal > Certificates. Right-click on the Certificates folder, and select All Tasks > Import…

i. On the Certificate Import Wizard Welcome Screen, click Next to continue.

j. In the Open File dialog, you will need to change the file type by selecting the "Personal Information Exchange (*.pfx, *.p12) option from the list. Then browse to find the certificate file provided by Salentica (hint: the certificate file will have a .p12 extension). Select the .p12 file and click OK.

k. In the password field, copy and paste the password provided to you by Salentica. The password will be found in a file called "Certificate Password.txt". If you are unable to copy/paste the password, please be very careful when typing it manually. Password is case sensitive. Click Next.

l. Click Next.

m. Click Next.

n. You should see this message. Click OK.

o. Back in the MMC console, you should see the new Salentica Data Broker certificate in the list.

p. You may now close the MMC console, and click No when prompted to save your changes.

The Connector is now installed and configured for use.

5. Testing the Macro and Script Run Successfully: (APX ONLY, Go to Step 6 for Axys Install)

a. In APX go to Reports and ‘Manage all Macros'. Search for the ‘salcar’ macro and open the macro by clicking on it. Next, click on ‘Run Macro’. Check to see if you receive any error messages during this test. See below in the Macro Common Errors section to address errors. If no errors happen proceed to the Output path folder 'WorkInProgress’ to see if the salcar.txt file exists. Delete this test file and then move on to testing the Script.

Common Error: Invalid Path: This could be based on the curly brackets {} being used at the beginning and end of the Output Path location. (Ex: {C:\Salentica\AdventConnector\WorkInProgress\salcar.txt} )

b. In APX go to Automation and ‘Scripts’ and search for the salcar script. Next, click on ‘Run’. Check to see if recieve any error messages during this test. If no errors happen proceed to the Output path folder 'WorkInProgress’ to see if the salcar.txt file exists. Delete this test file and testing will be complete.

6. Test the Advent Connector via the Command Prompt

a. After successfully testing the APX Macro and Script functionality, next test the Advent Connector's ability to generate the .txt file. To perform this step for either Axys or APX installs, open up the Command Prompt in Windows by using the Search Bar and type ‘cmd’.

b. Open the application using ‘Run as Administrator'. Inside the prompt type or copy the following text. cd “C:\Salentica\AdventConnector\”.

c. Next type or copy the following text. Salentica.Advent.Connector.exe /generate. This will kick off the automation and test if the salcar.txt file is generated in the 'WorkInProgress’ folder. If this file is created then your testing is complete.

7. Schedule the Integration to Run Daily

Perform this step on the identified server or workstation where the Advent Client Tools are installed, while logged in as a member of the Local Administrators group. Before turning on the scheduler, make sure you have a 15 seconds scheduler that will update the registry entry.

Running Scripts as Scheduled Tasks

You can run scripts automatically by incorporating them into Windows Scheduled Tasks. This way you do not have to remember to start scripts before you leave the office. The scripts can run on a routine basis, automatically, without any input from you. For details about Windows Scheduled Tasks, see your Windows documentation.

Important Notes for APX Administrators

APX requires user authentication to run scripts. This means that you must incorporate a username and password into your scheduled task. That user must also log in at least once to the machine that is running the scheduled task. When a user logs in to Windows for the first time on a machine, Windows creates the user's profile locally on that machine, which is required for the scheduled task to execute successfully. When you log in to APX with an APX user name and password (as opposed to with a Windows-integrated login), the ServerURL registry key is updated with a value that ends in "APXLogin" (Example: http://APXWebServer/APXLogin/). Nevertheless, to run scripts as scheduled tasks, this registry key must be set up to support Windows authentication. This means it must end in "APX," similar to http://APXWebServer/APX/. You also need to make sure that the key is pointing to the correct virtual directory. You can set the ServerURL key up either directly within your automation commands or before running automation, manually.

Setting The ServerURL Key In Your Script

Updating the ServerURL registry key is simple when you use the Advent scripting command, AdvScriptRunner, to run attended automation. To do so, you include a -url parameter immediately after the scripting command to identify the APX Web server's URL.

Example: AdvScriptRunner -url http://APXWebServer/Apx SCRIPT <ScriptShortName>...

Create a new Windows-integrated user

See this article for instructions to create a new user.

Setting The ServerURL Key Manually

If you prefer to manually update the registry key (instead of including the -URL parameter in your automation), Advent recommends that you do so each time you plan to run unattended automation, in case the registry key has been reset by other login sessions. Depending on whether the machine on which you are running the automation is a 32-bit machine or a 64-bit machine you must update one of these keys on the automation machine:

32-bit machine: HKEY_LOCAL_MACHINE\Software\Advent\ApxAuthClient\ServerURL

64-bit machine: HKEY_LOCAL_MACHINE\Software\Wow6432Node\Advent\ApxAuthClient\ServerURL

As mentioned, when you log in to APX with a username and password, the ServerURL registry key is updated with a value similar to "http://APXWebServer/APXLogin/." But to run scripts as scheduled tasks, this registry key must end in "APX," similar to "http://APXWebServer/APX/." To prevent scripts from failing, export the ServerURL key (without the "Login" text) as a registry file (*.reg). Then incorporate a command into your script that, before anything else, imports the correct key.

Here's an example for a 32-bit machine:

In your Windows Registry, browse to HKEY_LOCAL_MACHINE\Software\Advent\ApxAuthClient\<Your APX Release>, and select the ServerURL registry key. If necessary, remove "Login/" from the end of the registry key value. Then choose File > Export, and save the registry key as ServerURL.reg.

Next, update your nightly script so that it imports the correct ServerURL key before completing any other tasks. The following batch file commands update the ServerURL key (which was previously exported to D:\ServerURL.reg), and then exports price data.

Example: regedit.exe /s d:\ServerURL.reg (this can be saved into a bat file)

Installation Steps

a. Click the Windows Start button and type "Run" (without the quotes) and hit enter. You should get the Run dialog.

b. In the Open box, type ‘taskschd.msc’ and click ok. This will launch the Windows Task Scheduler.

c. Inside the Task Scheduler, click 'Create Task' from the Action Pane.

d. On the General Tab, provide a Name for the scheduled task.

e. Select the option to Run when the user is logged.

f. Select the option to Run with the highest privileges.

g. Next click the 'Triggers' tab. On the Triggers tab, click 'New'. We suggest the following settings: Weekly, Tuesday through Saturday.

h. Select a time of day by which your Advent data is normally priced and reconciled. You want this integration to run after your data is completely reconciled for the previous day.

i. Ensure the 'Enabled' box is checked, and click ok to save this Trigger.

j. Next click the ‘Actions' tab. On the Actions tab, click 'New’

k. Browse to the installation folder, and select the "Salentica.Advent.Connector.exe" file.

l. In the 'Start in' box, please paste in the folder location of the Connector. In the example here, the value in the 'Start in' box is C:\Salentica\AdventConnector

m. Click OK.

n. Now, click on OK on the Create Task window. You should now see your new Scheduled Task in the list.

o. If this scheduler is setup on a server, please make sure you leave the user connected. If the scheduler was configured through a Remote Desktop instance, when you're done, select disconnect, DO NOT SIGN OFF OR LOG OUT.

8. Run a Manual Load

a. To run the integration manually, you must login with a user with access to the server.

b. Browse to the installation folder, and select the "Salentica.Advent.Connector.exe" file.

The installation folder can have any name and will not necessarily match the example below. It is best to note the name of the location on behalf of the client.

c. In the 'Start in' box, paste in the folder location of the Connector. In the example here, the value in the 'Start in' box is C:\Salentica\AdventConnector.

If the integration is already set up to run through the Task Scheduler, the file location can be found in the Program/script window.