ks-iris-lib

Description

The purpose of this package is to collect a set of general-purpose utility classes, similar to ‘commons’ packages available for other programming languages (such as Java).

• ks.lib.archive : interoperability business operations to archive messages
• ks.lib.file : file utility classes and interoperability adapters/operations/services dealing with files
• ks.lib.hl7 : HL7 utility classes and interoperability adapters/operations/services dealing with HL7 messages
• ks.lib.interop : interoperability utility classes
• ks.lib.io : I/O utility classes
• ks.lib.json : JSON utility classes
• ks.lib.object : objects utility classes
• ks.lib.purge : interoperability message purge utilities
• ks.lib.record : (yet another?) simple record mapper
• ks.lib.test : unit testing utility classes
• ks.lib.xml : XML utility classes

Feel free to comment, review and contribute !

Usage

Once you clone the new repo to your laptop and open VSCode (with the InterSystems ObjectScript Extension Pack installed) you’ll be able to start development immediately.

Documentation

Documentation is available in the class reference (see http://localhost:your_web_port/csp/documatic/%25CSP.Documatic.cls) and some examples in the unit tests.

Both are still sparse, I’m working on it ;-)

Prerequisites

Make sure you have git and Docker desktop installed.

Installation

Clone/git pull the repo into any local directory

$ git clone https://github.com/theanor/ks-iris-lib.git

Open the terminal in this directory and call the command to build and run InterSystems IRIS in container:
Note: Users running containers on a Linux CLI, should use “docker compose” instead of “docker-compose”
See Install the Compose plugin

$ docker-compose up -d

To open IRIS Terminal do:

$ docker-compose exec iris iris session iris -U USER
DEV>

To exit the terminal, do any of the following:

Enter HALT or H (not case-sensitive)

How to start the development

This repository is ready to code in VSCode with the ObjectScript plugin.

Install VSCode, Docker and the InterSystems ObjectScript Extension Pack plugin and open the folder in VSCode.

Open the /src/cls/PackageSample/ObjectScript.cls class and make changes - it will be compiled in the running IRIS docker container.

Feel free to delete the PackageSample folder and place your ObjectScript classes in the form
/src/organisation/package/Classname.cls

Read more about folder setup for InterSystems ObjectScript and here on the naming convention

Running unit tests

To run test, use VSCode test harness or zpm :

USER> zpm "ks-lib test -v"

What else is inside the repository

.github folder

Contains two GitHub actions workflows:

1. github-registry.yml
   Once changes pushed to the repo, the action builds the docker image on Github side and pushes the image to Github registry that can be very convenient to further cloud deployement, e.g. kubernetes.
2. objectscript-qaulity.yml
   with every push to master or main branch the workflow launches the repo test on objectscript issues with Objectscript Quality tool, see the examples. This works if the repo is open-source only.

Both workflows are repo agnostic: so they work with any repository where they exist.

.vscode folder

Contains two files to setup vscode environment:

.vscode/settings.json

Settings file to let you immediately code in VSCode with VSCode ObjectScript plugin)

.vscode/launch.json

Config file if you want to debug with VSCode ObjectScript

src folder

Contains source files.
src/iris contains InterSystems IRIS Objectscript code

test folder

Contains unit tests for the ObjectScript classes

docker-compose.yml

A docker engine helper file to manage images building and rule ports mapping an the host to container folders(volumes) mapping

Dockerfile

The simplest dockerfile which starts IRIS and imports code from /src folder into it.
Use the related docker-compose.yml to easily setup additional parametes like port number and where you map keys and host folders.

iris.script

Contains objectscript commands that are feeded to iris during the image building

module.xml

IPM Module’s description of the code in the repository.
It describes what is loaded with the method, how it is being tested and what apps neeed to be created, what files need to be copied.

Read about all the files in this artilce

Troubleshooting

If you have issues with docker image building here are some recipes that could help.

1. You are out of free space in docker. You can expand the amount of space or clean up maually via docker desktop. Or you can call the following line to clean up:

docker system prune -f

2. We use multi-stage image building which in some cases doesn’t work. Switch the target to builder from final in the docker compose and try again.