User Manual, Rest API Guide, HA Cluster, Release Notes

1. Mirror121 Requirements

Mirror121 is a Java based application, designed to mirror data from tables in Salesforce into your local database. This mirroring process is done using Salesforce’s SOAP API and Bulk API.

architecture diagram

What you need:
- Salesforce organization
- Salesforce User with sufficient Rights
- Server with one of supported operating systems - Operating System
- Database into which all mirrored data will be stored

1.1. Salesforce

For ideal communication between Salesforce and Mirror121 we recommend you to set up authentication credentials with sufficient rights.

1.1.1. User Access Rights

Mirror121 application communicates with Salesforce via Web Services. We are using API library provided by Salesforce itself. It contains Partner API for synchronous calls and Bulk API for asynchronous calls. This library needs Authentication credentials which can be set in Settings (see Salesforce settings).

1.2. Application Requirements

Mirror121 is a Java web application, meaning it runs centrally on a server, and users interact with it throughout web browser from any computer.

1.2.1. Hardware

Mirror121 runs on any reasonably fast PC. See the minimal recommended hardware configuration.

  • Dual core CPU (Intel or AMD)

  • 2GB RAM

  • 1GB HDD for installation

  • Additional 5GB for log files

These requirements expect that only Mirror121 runs on that machine. You will need to run separate database server for mirror database. Of course you may use your existing infrastructure for that database.

Estimating required storage space

Mirror121 keeps a log of all activities - the estimated storage required for these logs is around 80MB per year.

Mirror121 also creates separate activity log for each synchronization run. The storage required for these logs vary depending on how many synchronizations you have, how often you synchronize them and how many records are being synchronized. Naturally, the longer you use Mirror121 more space for logs is required. See the examples below.

Table 1. Examples of required storage for activity logs
Amount of data Estimated storage required per year

Big (~150,000 updated records) synchronization every day

~ 45 MB per year

Big (~150,000 updated records) synchronization every hour

~ 1 GB per year

Smaller (~10,000 updated records) synchronization every day

~ 3 MB per year

Smaller (~10,000 updated records) synchronization every day

~ 72 MB per year

Then the total storage required per year can be calculated as:

Storage per year = 80MB + (number of big daily synchronizations * 45)MB + (number of small daily synchronizations * 3)MB + (number of big hourly synchronizations * 1000)MB + (number of small hourly synchronizations * 72)MB

1.2.2. Java

Java is a piece of software that has to be installed on your computer. Mirror121 does not work without it. Currently, we support AdoptOpenJDK 11 LTS (HotSpot).

On Windows, an up-to-date version of Java is included in the installation package. On Linux or Mac, you have to install it yourself.

Java Is Provided Free Of Charge

Since Java 11, Oracle (the company that owns and develops Java) has changed licensing terms and support model. This topic is quite complex but the important message is that you don’t have to pay for Java.

There are several distributions of Java available:

  • Please, use Open JDK builds from AdoptOpenJDK. More specifically, use Open JDK 11 LTS - HotSpot.

  • Please, avoid releases of Oracle JDK. These are paid and come with Oracle’s commercial support.

1.2.3. Application server

Mirror121 runs on Apache Tomcat web server which is included in the installation package. We upgrade the Tomcat to the latest version on a regular basis.

1.2.4. Databases

Mirror121 uses two databases.

  • Configuration database - stores metadata, i.e. what to synchronize, when to synchronize, etc.

  • Mirror database - stores data mirrored from Salesforce

Configuration DB and mirror DB may use different database servers. However, the best practice is to have one database server containing two databases. For more information see Database Configuration section.

Table 2. Supported databases
Database Version Comments

Oracle

11g and newer

MySQL

5.5 and newer

Community version MariaDB is also supported

Microsoft SQL Server

2008 and newer

PostgreSQL

9.2 and newer

Snowflake

All versions

Snowflake can be used as a mirror database. It cannot be used as a configuration database.

H2

1.3.172

Embedded file-based database. Suitable only for evaluation.

1.2.5. Browser

Mirror121 runs on all modern web browsers such as Google Chrome, Mozilla Firefox and Internet Explorer 8 or higher.

1.2.6. Operating System

Mirror121 is operating system agnostic. It can run on any system which supports Java.

Supported platforms

  • Microsoft Windows XP 32/64 bit

  • Microsoft Windows 7 32/64 bit

  • Microsoft Windows 10 32/64 bit

  • Microsoft Windows Server 2003 32 bit

  • Microsoft Windows Server 2008 R2 64 bit

  • Microsoft Windows Server 2012 R2 64 bit

  • Microsoft Windows Server 2016

  • Microsoft Windows Server 2019

  • Linux

2. Installing Mirror121

Mirror121 can be installed either using Windows Installer or manually from a ZIP package. Using the Windows Installer is the most easiest and straightforward way to install and configure Mirror121. On Linux you have to do the installation and configuration manually.

2.1. Prerequisites

You need two databases on your database server - configuration database and mirror database. See Database Configuration chapter.

If you don’t have the databases yet, you can use H2 database which is embedded into Mirror121. This will give you an opportunity to test Mirror121 even before your database administrators create the databases for you. Just note, that H2 is not suitable for production environment.

2.2. Windows Installer

2.2.1. Express installation

  1. Run the Installer - Go to a location to where you downloaded Mirror121 installation file and run it.

  2. First Step - Simply click next.

    welcome

  3. License Agreement - Please go through a license agreement and then confirm by clicking on "I agree".

    license

  4. Selecting the action - Select "Express Install" option and click next.

    type express

  5. Summary - Here you can see summary. It shows installation location, used ports windows service and such.

    express summary

  6. Installing - Window with a progress bar.

    installing

  7. Finish - Final screen. After clicking on "Finish", your default browser will be opened and application itself will load.

    finished

2.2.2. Custom installation

  1. Run the Installer - Go to a location to where you downloaded Mirror121 installation file and run it.

  2. First Step - Simply click next.

    welcome

  3. License Agreement - Please go through a license agreement and then confirm by clicking on "I agree".

    license

  4. Selecting the action - Select "Custom Install" option and click next.

    type custom

  5. Selecting the Location - If you would like to install Mirror121 into a location different to default one, feel free to click "Browse" and select your desired location. Once you are done selecting a location, just click "Next".

    location

  6. Configuring Ports and Host - This screen is here for you to change host name and ports.

    ports host

  7. Selecting the Database - Here you choose can which database you are going to use

    This step is about selecting configuration database. If you wish to read more about mirror db, please see mirror db section

    db choose

    Now you can input information necessary to correctly set mirror database.

    • Database Type: Choose a database you are going to use

    • Server: Address of a server where the database is running

    • Port: A port on which the database is running

    • Database: Database name, SID etc.

    • Username: username of a database user through which the Mirror121 is going to access the database

    • Password: password for that user

      db sql server

      NOTE:
      Postgres, SQL Server - If you wish to use different schema than public, it is possible too. Just fill the field Schema with the name of your desired schema.

  8. Setting the Service - If you want to run Mirror121 as a service, leave the checkbox checked. Windows service is good if you want to run Mirror121 automatically after the operating system starts up. You can change the service name. This is useful if you need to install multiple instances of Mirror121.
    You can also change the system account under which the service will be running, e.g. if you create a special account on server just for running Mirror121.

    service

  9. Summary - Here you can see summary. It shows installation location, used ports windows service and such.

    custom summary

  10. Installing - Window with a progress bar.

    installing

  11. Finish - Final screen. After clicking on "Finish", your default browser will be opened and application itself will load.

    finished

2.3. Installation On Linux

  1. Create Mirror121 directory /opt/Mirror121. You are free to choose a different directory.

    mkdir /opt/Mirror121

  2. Download Java and store it into /opt/Mirror121/tmp directory. More specifically, download AdoptOpenJDK 11 LTS - HotSpot.

  3. Download Mirror121 ZIP package and store it into /opt/Mirror121/tmp directory.

  4. Unpack AdoptOpenJDK and Mirror121:

    cd /opt/Mirror121/tmp
tar zxvf OpenJDK11U-jdk_x64_linux_hotspot_CURRENT-JAVA-VERSION.tar.gz
unzip mirror121-CURRENT_MIRROR121-VERSION.zip

  5. Copy unpacked directories: copy Java to /opt/Mirror121/jre and Mirror121 to /opt/Mirror121.

    cp -r /opt/Mirror121/tmp/jdk-CURRENT-JAVA-VERSION/. /opt/Mirror121/jre
cp -r /opt/Mirror121/tmp/mirror121-CURRENT-MIRROR121-VERSION/. /opt/Mirror121

  6. Remove temporary folder

    cd /opt/Mirror121
rm -rf /opt/Mirror121/tmp

  7. Edit mirror121.properties

    1. mirror121.host property - by default, it is set to "localhost". That means, you can access Mirror121 only from the machine where you installed it. If you want to be able to acces Mirror121 from outside this machine set the property to its network name. See Application URL Configuration for details on how to change the host name.

    2. Provide a connection to your configuration database:

      Database Server config.db.type config.jdbc.url

      SQL Server

      mssql

      jdbc:jtds:sqlserver://<SERVER>:<PORT>/mirror121_config;instance=<INSTANCE-NAME>

      Oracle

      oracle

      jdbc:oracle:thin:@<SERVER>:<PORT>:<SID>
      jdbc:oracle:thin:@<SERVER>:<PORT>/<SERVICE-NAME>

      MySQL

      mysql

      jdbc:mysql://<SERVER>:<PORT>/mirror121_config

      PostgreSQL

      postgres

      jdbc:postgresql://<SERVER>:<PORT>/mirror121_config

      H2 (Embedded)

      h2

      jdbc:h2:~/h2/mirror121_config;MVCC=TRUE

      Also, provide username (config.jdbc.username) and password (config.jdbc.username).

  8. Start Mirror121.

    /opt/Mirror121/run.sh

  9. Open Mirror121 in your favorite web browser on the following URL: \http://<value of mirror121.host property>:<value of mirror121.port>.
     
    The default value is http://localhost:9191.

2.3.1. Service Installation

Optionally, you can install Mirror121 as a service. The service will automatically start when operating system starts.

  1. Open Terminal

  2. Copy a script responsible for starting and stopping Mirror121 init.d directory.

    sudo cp /opt/Mirror121/bin/init.d/mirror121.sh /etc/init.d/mirror121

  3. Make the init script executable:

    sudo chmod a+x /etc/init.d/mirror121

  4. Place symlinks in the run-level directories to start and stop this script automatically.

    1. For Debian based systems:

      update-rc.d mirror121 defaults

    2. For RedHat based systems:

      chkconfig --add mirror121
      The mirror121.sh script contains chkconfig settings

2.4. What Is Installed

We have described the installation process on both Windows and Linux server. Let’s have a look at files we installed.

File & Directory Description

/mirror121.properties

Main configuration file. Contains a connection to the configuration database and Mirror121 base URL. If you want to know more about setting a different base url or changing port, please see chapter Deployment URL

/mirror121-https.jks

Contains a certificate and a private key. Used when you configure Mirror121 to use HTTPS protocol.

/run.bat

Starts Mirror121 on Windows. Used only if a service is not installed.

/run.sh

Starts Mirror121 on Linux.

/shutdown.bat

Stops Mirror121 on Windows. Used only if a service is not installed.

/shutdown.sh

Stops Mirror121 on Linux.

/Uninstall.exe

Uninstalls Mirror121 from Windows.

/Uninstall.info

Stores data needed for uninstallation.

/bin

Contains Apache Tomcat web server.

/conf

Apache Tomcat configuration files.

/jre

Java runtime environment binaries.

/lib

Apache Tomcat classes and libraries.

/license

License files.

/logs

Folder used for both Mirror121 and Tomcat logs.

/logs/activityLogs

Folder used for synchronizations logs. Each synchronization run has its own log file. The files are located by this pattern: <synchronizationId>/<yyyy-MM>/<logId>.log.

/mirror121

Contains all Mirror121 specific application files like configurations, WAR file, documentation and data directory for embedded H2 database and a folder for mirrored attachments.

/mirror121/data

When embedded H2 database is used, this folder stores database files.

/mirror121/docs

Folder contains Mirror121 documentation.

/mirror121/jce

Contains Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files

/mirror121/conf

Mirror121 configuration files. Do not modify. If you need no make a change, modify the main configuration file /mirror121.properties.

/mirror121/webapp

Mirror121 war archive.

/webapps

Used by Apache Tomcat.

/work

Used by Apache Tomcat.

If you want to make sure no directory is missing or you are not sure how Mirror121 installation should look like, please checkout the following directory structure. We omitted directories nested too deep and all files.

.
├── bin
│   ├── experimental
│   └── init.d
├── conf
│   └── Catalina
├── jre
│   ├── bin
│   ├── lib
│   ├── man
│   └── plugin
├── lib
├── logs
│   └── activityLogs
├── mirror121
│   ├── conf
│   ├── data
│   ├── docs
│   ├── license
│   ├── trusted-certificates
│   └── webapp
├── mirror121-themes
├── temp
│   └── attachment
├── webapps
│   └── ROOT
└── work
    └── Catalina

2.5. Uninstall Mirror121

2.5.1. Windows

  1. Go to installation folder.

  2. Open Uninstall.exe and follow the instructions.

2.5.2. Linux

If you have installed Mirror121 manually from an archive file, just follow these steps.

  1. Stop Mirror121

  2. Delete "/opt/Mirror121" directory.

Uninstall Linux Service

  1. Open a Terminal.

  2. Log in as root user.

  3. Remove Service:

    1. For Debian based systems:

      update-rc.d -f mirror121 remove

    2. For RedHat based systems:

      chkconfig --del mirror121

3. Running the Setup Wizard

When you first access Mirror121 you will be redirected to the configuration wizard. It will walk you through basic Mirror121 configuration. Once you finish the Configuration Wizard data will be stored to the database and Mirror121 will be immediately ready to use.

3.1. Walkthrough

3.1.1. License

On this page you can provide a license which you received to your mailbox.

license

3.1.2. Salesforce

Enter information about Salesforce instance. You can test the configuration using Test Connection button.

Test Connection button checks:

  • Whether the user can authenticate

  • Whether the user is authorized to access all necessary data

If your do not know user’s security token, see Obtaining security token section.