How do I run a script? Instructions from a non-programmer using the Orgsync script from CashCtrl as an example.

Tutorial: Synchronize two organizations / clients with a Java Script via the command line.

  1. Preparation: install Java, download script
  2. Set parameters
  3. Execute script with Windows
  4. Execute script with Mac OS
  5. Good to know / Other optional parameters

1. Preparation

Before the Java Script can be executed, Java must be installed on the computer. If Java is already existing, this step can be skipped.

To install Java, go to the Oracle website and download the Java Development Kit (JDK) version 17 (for Windows / MacOS / Linux). Follow the installation instructions.

Furthermore download the Orgsync Script and unzip it. Included is the Readme.txt, which explains the parameters.

Screenshot of the Java Downloads
orgsync-binary.zip
Last updated: 24.07.2022

2. The script explained

java -jar orgsync.jar -p -orga mariamuster -keya Hu4hpRl7zT40uUbdb4Eed4dBbf20Ff87 -orgb hansmuster -keyb aF3cb2Uu9f304dD3f8o5ce81Oo28Pe1E


java -jar orgsync.jar is needed to start the script.
-p is used to synchronize persons, additionally or alternatively -a can be used here for articles.
orga stands for organization A.
keya stands for the API Key of organization A (this can be copied or created via Settings Users & Roles).
orgb stands for organization B.
keyb stands for the API Key of organization B.

Screenshot of a code snippet of the Orgsync script from CashCtrl

3. Running the script in Mac Terminal (MacOS)

First open the Mac Terminal via the Launchpad and navigate to the folder where the script is stored. This works in the command line with the command cd (cd stands for change directory). In the example, the script file orgsync.jar is located in the folder orgsync-binary, which is located in the folder Downloads, so the command cd downloads is used to change to the Downloads folder and then cd orgsync-binary is used to change to the subfolder orgsync-binary.

So then the script can be executed with the desired parameters:

java -jar orgsync.jar -p -orga mariamuster -keya Hu4hpRl7zT40uUbdb4Eed4dBbf20Ff87 -orgb hansmuster -keyb aF3cb2Uu9f304dD3f8o5ce81Oo28Pe1E

 

Screenshot of the Mac terminal with the command to run the Orgsync script

4. Running the script in the Terminal (Windows 11) or with Command prompt  (Windows 10)

Open the Windows terminal by clicking on the Windows icon and using the search function. Use the command cd (cd stands for change directory) to navigate to the folder where the script file orgsync.jar is located. In the example the file is located in the folder orgsync-binary, which is located in the folder Downloads, so use the command cd downloads to change to the Downloads folder and then use cd orgsync-binary to change to the subfolder orgsync-binary.

So then the script can be executed with the desired parameters:

java -jar orgsync.jar -p -orga mariamuster -keya Hu4hpRl7zT40uUbdb4Eed4dBbf20Ff87 -orgb hansmuster -keyb aF3cb2Uu9f304dD3f8o5ce81Oo28Pe1E

Screenshot of the Windows terminal with the command to run the Orgsync script

5. Good to know / Other optional parameters

  • On Mac, full disk access must be granted for the terminal, otherwise an error message will appear.
  • Different filters can be applied to the synchronization. E.g. for persons with -pf (person filter) or -af (article filter). The possible keys are e.g.
    category - The name of the root category to be synchronized. This category must exist in both organizations.
    onlyActive - Flag to include only active articles/persons. Possible values: true, false
    onlyNotes - Flag to include only entries with notes (true, false)
    onlyWithImages - Flag to include only articles/persons with pictures (true, false)
    onlyWithoutCategory - Flag to include only entries without a category (true, false)
    query - Full text search request (Text)
    onlyCostCenters - Flag to inlcude only entries with cost centers (true, false)
    onlyRestock - Flag to include only articles that need to be replenished (true, false)
    Example: -pf category=Employee onlyActive=true -af category=Services onlyWithImages=true
  • The mode of synchronization can be set with the command -fsm. Possible values are 'none', 'all' or 'onlyAttached', default value is 'onlyAttached'.
    Example: -fsm all
  • Another optional setting is the last synchronization delta with the command -lsd. This specifies the time in milliseconds that must elapse since the last synchronization and the last edited data set before it is synchronized again, default value is 10 seconds (100 milliseconds).
    Example: -lsd 600 for one minute (corresponds to 600 milliseconds).
Portrait of CashCtrl Community Manager Moritz

Background of the tutorial

The idea behind this tutorial is to show how CashCtrl can be extended and customized. Furthermore we want to show how someone can execute a script who is not a developer. Therefore our community manager dared to do this task - and got the desire for more!
It's actually not that difficult :-)

Help

Could we help?

Tutorials

The most important functions explained briefly and simply.

Forum

Exchange ideas with other users in our forum.

Documentation

The comprehensive reference work with index and search.