Migrating from Anaplan Connect 1.3.x.x. to Anaplan Connect 1.4.x

AnaplanOEG · October 2018

This article covers the necessary steps for you to migrate your Anaplan Connect (AC) 1.3.x.x script to Anaplan Connect 1.4.x. For additional details and examples, refer to the latest Anaplan Connect User Guide.

The changes are:

New connectivity parameters.
Replace reference to Anaplan Certificate with Certificate Authority (CA) certificates using new parameters.
Optional Chunksize & Retry parameters.
Changes to JDBC configuration.

New Connectivity Parameters

Add the following parameters to your Anaplan Connect 1.4.x integration scripts. These parameters provide connectivity to Anaplan and Anaplan authentication services.

Note: Both of the urls listed below need to be whitelisted with your network team.

-service "https://api.anaplan.com/"
-auth "https://auth.anaplan.com"

Certificate Changes

As noted in our Anaplan-Generated Certificates to Expire at the End of 2019 blog post, new and updated Anaplan integration options support Certificate Authority (CA) certificates for authentication. Basic Authentication is still available in Anaplan Connect 1.4.x, however, the use of certificates has changed. In Anaplan Connect 1.3.x.x, the script references the full path to the Anaplan certificate file.

For example:

-certificate "/Users/username/Documents/AnaplanConnect1.3/certificate.pem"

In Anaplan Connect 1.4.x the CA certificate can be referenced via two different options. Examples of both options are included at the end of this article as well as in the Anaplan Connect 1.4.x download.

Option 1: Direct Use of the Private Key with Anaplan Connect

Use your Private Key with Anaplan Connect by providing to certificate, private key and optional private key passphrase.

For example:

If your private key has been encrypted use the following:

CertPath="FullPathToThePublicCertificate"
PrivateKey="FullPathToThePrivateKey:Passphrase"

If your private key has not been encrypted then the passphrase can be omitted, however the colon is still needed in the path of the private key.

CertPath="FullPathToThePublicCertificate"
PrivateKey="FullPathToThePrivateKey:"

To pass these values to Anaplan Connect 1.4.x, use these command line parameters:

-certificate {path to the certificate file}
-privatekey {path to the private key file:}{passphrase}

These parameters should be passed as part of the credentials in the script:

Credentials="-certificate ${CertPath} -privatekey ${PrivateKey}"

Option 2: Create a Java Keystore

A Java Keystore (JKS) is a repository of security certificates and their private keys. Refer to this video for a walkthrough of the process of getting the CA certificate into the key store. You can also refer to Anaplan Connect User Guide for steps to create the Java key store.

Once you have imported the key into the JKS, make note of this information:

Path to the JKS (directory path on server where JKS is saved)
The Password to the JKS
The alias of the certificate within the JKS.

For example:

KeyStorePath="/Users/username/Documents/AnaplanConnect1.4/my_keystore.jks"
KeyStorePass="your_password"
KeyStoreAlias="keyalias"

To pass these values to Anaplan Connect 1.4.x, use these command line parameters:

-keystore {KeystorePath}
-keystorealias {KeystoreAlias}
-keystorepass {KeystorePass}

These parameters should be passed as part of the credentials in the script:

 Credentials="-keystore ${KeyStorePath} -keystorepass ${KeyStorePass} -keystorealias ${KeyStoreAlias}"

Chunksize

Anaplan Connect 1.4.x allows for custom chunk sizes on files being imported. The -chunksize parameter can be included in the call with the value being the size of the chunks in megabytes. The chunksize can be any whole number between 1 and 50.

-chunksize {SizeInMBs}

Retry

Anaplan Connect 1.4.x allows for the client to retry requests to the server in the event that the server is busy. The -maxretrycount parameter defines the number of times the process retries the action before exiting. The -retrytimeout parameter is the time in seconds that the process waits before the next retry.

-maxretrycount {MaxNumberOfRetries}
-retrytimeout {TimeoutInSeconds}

Changes to JDBC Configuration

With Anaplan Connect 1.3.x.x the parameters and query for using JDBC are stored within the Anaplan Connect script itself.

For example:

Operation="-file Sample.csv' -jdbcurl 'jdbc:mysql://localhost:3306/mysql?useSSL=false' -jdbcuser 'root:Welcome1' -jdbcquery 'SELECT * FROM py_sales' -import 'Sample.csv' -execute"

With Anaplan Connect 1.4.x. the parameters and query for using JDBC have been moved to a separate file. The name of that file is then added to the AnaplanClient call using the -jdbcproperties parameter.

For example:

Operation="-auth 'https://auth.anaplan.com' -file 'Sample.csv'  -jdbcproperties 'jdbc_query.properties' -import 'Sample.csv' -execute "

To run multiple JDBC calls in the same operation, a separate jdbcpropeties file will be needed for each query. Each set of calls in the operation should include then following parameters: -file, -jdbcproperties, -import, and -execute. In the code sample below each call is underlined separately.

For example:

Operation="-auth 'https://auth.anaplan.com' -file 'SampleA.csv' -jdbcproperties 'SampleA.properties' -import 'SampleA Load' -execute  -file 'SampleB.csv' -jdbcproperties 'SampleB.properties' -import 'SampleB Load' -execute"

JDBC Properties File

Below is an example of the JDBCProperties file. Refer to the Anaplan Connect User Guide for more details on the properties shown below. If the query statement is long, the statement can be broken up on multiple lines by using the \ character at the end of each line. No \ is needed on the last line of the statement. The \ must be at the end of the line and nothing can follow it.

jdbc.connect.url=jdbc:mysql://localhost:3306/mysql?useSSL=false
jdbc.username=root
jdbc.password=Welcome1
jdbc.fetch.size=5
jdbc.isStoredProcedure=false
jdbc.query=select * \
from mysql.py_sales \
where year = ? and month !=?;
jdbc.params=2018,04

CA Certificate Examples

Direct Use of the Private Key

Anaplan Connect Windows BAT Script Example (with direct use of the private key)

'@echo of

rem This example lists files in a model
set CertPath="C:\CertFile.pem"
set PrivateKey="C:\PrivateKeyFile.pem:passphrase"
set WorkspaceId="Enter WS ID Here"
set ModelId="Enter Model ID here"
set Operation=-service "https://api.anaplan.com" -auth "https://auth.anaplan.com" -workspace %WorkspaceId% -model %ModelId% -F
set Credentials=-certificate %CertPath% -privatekey %PrivateKey%

rem *** End of settings - Do not edit below this line ***

setlocal enableextensions enabledelayedexpansion || exit /b 1
cd %~dp0
set Command=.\AnaplanClient.bat %Credentials% %Operation%
@echo %Command%
cmd /c %Command%
pause

Anaplan Connect Shell Script Example (with Direct Use of the Private Key)

#!/bin/sh
# This example lists files in a model
set CertPath="/path/CertFile.pem"
set PrivateKey="/path/PrivateKeyFile.pem:passphrase"
WorkspaceId="Enter WS ID Here"
ModelId="Enter Model Id Here"

Operation="-service 'https://api.anaplan.com' -auth 'https://auth.anaplan.com' -workspace ${WorkspaceId} -model ${ModelId} -F"

#________________ Do not edit below this line __________________

if [ "${PrivateKey}" ]; then
    Credentials="-certificate ${CertPath} -privatekey ${PrivateKey}"
fi

echo cd "`dirname "$0"`"
cd "`dirname "$0"`"

if [ ! -f AnaplanClient.sh ]; then
    echo "Please ensure this script is in the same directory as AnaplanClient.sh." >&2
    exit 1
elif [ ! -x AnaplanClient.sh ]; then
    echo "Please ensure you have executable permissions on AnaplanClient.sh." >&2
    exit 1
fi
Command="./AnaplanClient.sh ${Credentials} ${Operation}"
/bin/echo "${Command}"
exec /bin/sh -c "${Command}"

Using a Java Keystore (JKS)

Anaplan Connect Windows BAT Script Example (Using a Java Keystore)

@echo off

rem This example lists files in a model

set Keystore="C:\YourKeyStore.jks"
set KeystoreAlias="alias1"
set KeystorePassword="mypassword"
set WorkspaceId="Enter WS ID Here"
set ModelId="Enter Model ID here"
set Operation=-service "https://api.anaplan.com" -auth "https://auth.anaplan.com" -workspace %WorkspaceId% -model %ModelId% -F
set Credentials=-k %Keystore% -ka %KeystoreAlias% -kp %KeystorePassword%
rem *** End of settings - Do not edit below this line ***

setlocal enableextensions enabledelayedexpansion || exit /b 1
cd %~dp0
set Command=.\AnaplanClient.bat %Credentials% %Operation%
@echo %Command%
cmd /c %Command%
pause

Anaplan Connect Shell Script Example (Using a Java Keystore)

#!/bin/sh

#This example lists files in a model 
KeyStorePath="/path/YourKeyStore.jks"
KeyStoreAlias="alias1"
KeyStorePass="mypassword"

WorkspaceId="Enter WS ID Here"
ModelId="Enter Model Id Here"

Operation="-service 'https://api.anaplan.com' -auth 'https://auth.anaplan.com' -workspace ${WorkspaceId} -model ${ModelId} -F"

#________________ Do not edit below this line __________________

if [ "${KeyStorePath}" ]; then
    Credentials="-keystore ${KeyStorePath} -keystorepass ${KeyStorePass} -keystorealias ${KeyStoreAlias}"
fi

echo cd "`dirname "$0"`"
cd "`dirname "$0"`"

if [ ! -f AnaplanClient.sh ]; then
    echo "Please ensure this script is in the same directory as AnaplanClient.sh." >&2
    exit 1
elif [ ! -x AnaplanClient.sh ]; then
    echo "Please ensure you have executable permissions on AnaplanClient.sh." >&2
    exit 1
fi
Command="./AnaplanClient.sh ${Credentials} ${Operation}"
/bin/echo "${Command}"
exec /bin/sh -c "${Command}"

Migrating from Anaplan Connect 1.3.x.x. to Anaplan Connect 1.4.x

New Connectivity Parameters

Certificate Changes

Option 1: Direct Use of the Private Key with Anaplan Connect

Option 2: Create a Java Keystore

Chunksize

Retry

Changes to JDBC Configuration

JDBC Properties File

CA Certificate Examples

Direct Use of the Private Key

Anaplan Connect Shell Script Example (with Direct Use of the Private Key)

Using a Java Keystore (JKS)

Anaplan Connect Windows BAT Script Example (Using a Java Keystore)

Anaplan Connect Shell Script Example (Using a Java Keystore)

Categories