Quick Start for contributors

Local development environment setup guide.

Prerequisites

Package management tools

Windows

Install Chocolatey

MacOS

Install Homebrew

Development tools

info

All following commands fow windows use Git bash

Essential

Windows

Install Git for Windows. Recommended settings for better command line experience:

• Add a Git Bash to Windows Terminal
• Use Windows default console window

note

In Git bash as a Local Administrator

choco install -y nodejs-lts

choco install -y yarn

choco install -y vscode

MacOS

brew install git

brew install node@18

brew install yarn

brew cask install visual-studio-code

Configuration

tip

You can skip this step if you have got access to ACE repository already

Create ssh key for ACE repositories

cd ~
mkdir -p .ssh
ssh-keygen -f ./.ssh/id_ace_rsa -t rsa -b 4096 -C "your_email@example.com"

# display public key
cat ./.ssh/id_ace_rsa.pub

Upload your public key to https://dev.azure.com/spnsdigital/_usersSettings/keys

Setup SSH host mapping

note

Make sure that your DevOps user is granted access to ACE git repositories

echo "Host ssh.dev.azure.com
  IdentityFile ~/.ssh/id_ace_rsa" >> ~/.ssh/config

mkdir -p ~/git/sapiens
cd ~/git/sapiens

Obtaining the source code

In ~/git/sapiens directory

git config --global core.autocrlf input
git clone git@ssh.dev.azure.com:v3/spnsdigital/sapiens-digital/sapiens-digital-ace-designer
git clone git@ssh.dev.azure.com:v3/spnsdigital/sapiens-digital/sapiens-digital-journey-api
git clone git@ssh.dev.azure.com:v3/spnsdigital/sapiens-digital/sapiens-digital-flow-runner
git clone git@ssh.dev.azure.com:v3/spnsdigital/sapiens-digital/sapiens-digital-cache-service
git clone git@ssh.dev.azure.com:v3/spnsdigital/sapiens-digital/sapiens-digital-ace-e2e

Starting ACE 4 locally

Authentication and dependency installation

Obtain tools to connect to sapiens-registry npm feed

Windows

Install sapiens-digital-ace-designer dependencies and start vscode

cd ~/git/sapiens/sapiens-digital-ace-designer
vsts-npm-auth -config .npmrc
yarn install
code .

MacOS

vsts-npm-auth is not supported in Linux/Mac. Follow the steps below to set up your credentials:

1. Copy the following contents into your local ~/.npmrc file:

; begin auth token
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/registry/:username=spnsdigital
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/registry/:_password=COPY_YOUR_PERSONAL_ACCESS_TOKEN
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/registry/:email=npm requires email to be set but doesn't use the value
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/:username=spnsdigital
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/:_password=YOUR_PERSONAL_ACCESS_TOKEN
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/:email=npm requires email to be set but doesn't use the value
; end auth token

2. Generate a personal access token with packaging read and write scopes.

3. Encode your newly generated personal access token to base64:

echo -n "YOUR_PERSONAL_ACCESS-TOKEN" | base64

4. In your ~/.npmrc file replace YOUR_PERSONAL_ACCESS_TOKEN placeholder with your base64 encoded token

5. Install sapiens-digital-ace-designer dependencies and start vscode

cd ~/git/sapiens/sapiens-digital-ace-designer
yarn install
code .

Starting the project

Start journey-api services

Install flow-runner dependencies

cd ~/git/sapiens/sapiens-digital-flow-runner/flow-runner-service
yarn install
cp .env.example .env

cd ~/git/sapiens/sapiens-digital-flow-runner
code .

Start flow-runner

Start journey-api UI

Linking local package dependencies

Some ACE services references packages from other ACE repositories, so for development purposes it may be necessary to link them locally instead of referencing published package version.

When local development is done, it's necessary to update referenced package versions in package.json file.

Flow runner service

Flow runner service uses ACE Designer runtime

cd ~/git/sapiens/sapiens-digital-ace-designer
yarn install

cd sapiens-digital-ace-designer-runtime
yarn build
yarn link

cd ~/git/sapiens/sapiens-digital-flow-runner/flow-runner-service
yarn link "@sapiens-digital/ace-designer-runtime"
yarn build