InterSystems ObjectScript is a scripting language to operate with data using any data model of InterSystems Data Platform (Objects, Relational, Key-Value, Document, Globals) and to develop business logic for serverside applications on InterSystems Data Platform.
Sending emails is a common requirement in integration scenarios — whether for client reminders, automatic reports, or transaction confirmations. Static messages quickly become hard to maintain and personalize. This is where the templated_email module comes in, combining InterSystems IRIS Interoperability with the power of Jinja2 templates.
Jinja2 is a popular templating engine from the Python ecosystem that enables fully dynamic content generation. It supports:
This will be a short article about Python dunder methods, also known as magic methods.
Dunder methods are special methods in Python that start and end with double underscores (__). They allow you to define the behavior of your objects for built-in operations, such as addition, subtraction, string representation, and more.
Some common dunder methods include:
__init__(self, ...): Called when an object is created.
%OnNew method in ObjectScript.__str__(self): Called by the str() built-in function and print to represent the object as a string.__repr__(self): Called by the repr() built-in function to represent the object for debugging.__add__(self, other): Called when the + operator is used.__len__(self): Called by the len() built-in function to return the length of the object.__getitem__(self, key): Called to retrieve an item from a collection using the indexing syntax.__setitem__(self, key, value): Called to set an item in a collection using the indexing syntax.In ObjectScript, we don't have the sugar syntax like in Python, but we can achieve similar behavior using dunder methods.
Example, we have imported a Python module, it has a function that returns a python list, and we want to use it in ObjectScript. We must use the __getitem__ dunder method to access the items in the list.
# src/python/article/dunder_example.py
def get_list():
return [1, 2, 3, 4, 5]
Class Article.DunderExample Extends %RegisteredObject
{
ClassMethod Run()
{
Set sys = ##class(%SYS.Python).Import("sys")
do sys.path.append("/irisdev/app/src/python/article")
set dunderExample = ##class(%SYS.Python).Import("dunder_example")
set myList = dunderExample."get_list"()
for i=0:1:myList."__len__"()-1 {
write myList."__getitem__"(i), !
}
}
}
Let's run it:
iris session iris -U IRISAPP '##class(Article.DunderExample).Run()'
This will output:
1
2
3
4
5
This demonstrates how to use dunder methods to interact with Python objects in an IRIS context, allowing you to leverage Python's capabilities while working within the ObjectScript environment.
A good use of dunder is to put at the end of your python script a if __name__ == "__main__": block to prevent the code from being executed when the script is imported as a module.
Remember, the first article explained that when you import a script, the code is executed. This block allows you to define code that should only run when the script is executed directly, not when it's imported.
Example:
# src/python/article/dunder_example.py
def get_list():
return [1, 2, 3, 4, 5]
if __name__ == "__main__":
print(get_list())
What you can do in python even with it's sugar syntax, you can do it in ObjectScript with dunder methods.
Are you curious about how to run Python scripts directly in your InterSystems IRIS or Caché terminal? 🤔 Good news it's easy! 😆 IRIS supports Embedded Python, allowing you to use Python interactively within its terminal environment.
How to access the Python Shell?
To launch the Python shell from the IRIS terminal, simply run the following command:
do##class(%SYS.Python).Shell()This opens an interactive Python shell inside the IRIS terminal. From here, you can write and run Python code just as you would in a normal Python environment.
Exiting the Shell:
>>> quit()
Modules what a topic! We don't have this notion in ObjectScript, but it's a fundamental concept in Python. Let's discover it together.
I see modules as an intermediate layer between classes and packages. Let see it by example.
A bad example :
# MyClass.py
class MyClass:
def my_method(self):
print("Hello from MyClass!")
When you try to use this class in another script, you would do:
# class_usage.py
from MyClass import MyClass # weird, right?
my_instance = MyClass()
my_instance.my_method()
Why this is a bad example?
First because file names should be in snake_case according to PEP 8, so it should be my_class.py.
Second, because you are importing a class from a file that has the same name as the class. This is not a good practice in Python.
I know this can be confusing, especially if you come from ObjectScript where classes are defined in files with the same name as the class.
So we just saw that modules can be a python file but without the .py extension.
But wait, does it mean that a python script is a module too? Yes, it is!
That's why you should be careful when importing a script, because it will execute the code in that script. See the Introduction to Python article for more details.
__init__.py FileWow, can a folder be a module? Yes, it can!
A folder can be a module if it contains an __init__.py file. This file can be empty or contain initialization code for the module.
Let's see an example:
src/python/article/
└── my_folder_module/
├── __init__.py
├── my_sub_module.py
└── another_sub_module.py
# my_folder_module/my_sub_module.py
class MySubModule:
def my_method(self):
print("Hello from MySubModule!")
# my_folder_module/another_sub_module.py
class AnotherSubModule:
def another_method(self):
print("Hello from AnotherSubModule!")
# my_folder_module/__init__.py
# This file can be empty or contain initialization code for the module.
In this case, my_folder_module is a module, and you can import it like this:
from my_folder_module import my_sub_module, another_sub_module
Or if you define an __init__.py file with the following content:
# my_folder_module/__init__.py
from .my_sub_module import MySubModule
from .another_sub_module import AnotherSubModule
You can import it like this:
from my_folder_module import MySubModule, AnotherSubModule
You see the subtility? You can import the classes directly from the module without specifying the sub-module, because the __init__.py file is executed when you import the module, and it can define what is available in the module's namespace.
When you import a module, Python looks for it in the directories listed in sys.path. This is a list of strings that specifies the search path for modules.
You can view the current sys.path by running the following code:
import sys
print(sys.path)
By default, it includes the current directory and other various directories depending on your Python installation.
You can also add directories to sys.path at runtime, which is useful when you want to import modules from a specific location. For example:
import sys
sys.path.append('/path/to/your/module')
from your_module import YourClass
This is why in the previous article, we added the path to the module before importing it:
Set sys = ##class(%SYS.Python).Import("sys")
do sys.path.append("/irisdev/app/src/python/article")
set my_module = ##class(%SYS.Python).Import("my_module")
What are the other directories in sys.path? They are usually:
How site-packages works? When you install a package using pip, it is installed in the site-packages directory, which is automatically included in sys.path. This allows you to import the package without having to specify its location.
🤨🔍 But how and where the site-packages directory are set and by who?
The site-packages directory is created during the installation of Python and is typically located in the lib directory of your Python installation. The exact location depends on your operating system and how Python was installed.
For example, on a typical Linux installation, the site-packages directory might be located at:
/usr/local/lib/python3.x/site-packages
On Windows, it might be located at:
C:\Python3x\Lib\site-packages
When you install a package using pip, it is installed in the site-packages directory, which is automatically included in sys.path. This allows you to import the package without having to specify its location.
import site
print(site.getsitepackages())
🤨🔍 When and where python interpreter reads the site.py file?
The site.py file (which is located in the standard library directory) is executed automatically when the Python interpreter starts. It is responsible for setting up the site-packages directory and adding it to sys.path. This file is located in the standard library directory of your Python installation.
In IRIS, we also have a site.py file, which is located in <installation_directory>/lib/python/iris_site.py. This file is executed when you start or import aa script/module in IRIS, and it sets up the sys.path for you.
Roughly, the iris_site.py file does the following:
site-packages directory<installation_directory>/lib/python/ directory to sys.path<installation_directory>/mgr/python/ directory to sys.pathsys.pathA module can be :
.py extension)__init__.py filesys.path listWorking on wrapping an IRIS Cache ObjectScript method that runs for a few seconds. Trying to get UI updates to show BEFORE the method runs in an async/await function. But it seems to be running synchronously rather than asynchronously . So my question is does IRIS/ObjectScript CSP pages support futures with JavaScript or does it run all synchronously.
InterSystems is pleased to announce that version 3.0.5 of the VS Code - ObjectScript extension has been released. This release includes many bug fixes, as well as changes to the telemetry data we collect. Collecting more product usage data helps InterSystems identify and prioritize fixes and enhancements that will have the most positive impact for you, our users. Personally identifiable information (PII) will never be collected, and telemetry can be disabled using the telemetry.telemetryLevel setting. The full list of data points that are collected can be found here. Thank you for using our
I am trying to catch an exception and write it to the Application Error Log, but cant find any details on how to do this in IRIS health.
Catch ex {Set logger = ##class(%Logger).%GetLogger("MyApp")Do logger.Error($ZError)}Cant seem to find the %Logger class either.
This will be a short article about PEP 8, the Python style guide.
In a nutshell, PEP 8 provides guidelines and best practices on how to write Python code.
snake_caseCamelCasesnake_caseUPPER_CASE_)
No need to say them all, but keep it in mind that will help you to understand other's code and help others to understand your code ^^.
Also, you may have heard about the words pythonic. Following PEP 8 is a way to write Python code that is considered "pythonic" (it's not only that but it's part of it).
In IRIS and especially in ObjectScript, we also have a style guide, which is mainly based on camelCase for variable names and PascalCase for class names.
Unfortunately, PEP 8 recommends using snake_case for variable names and functions.
And you already know it, in ObjectScript underscore (_) is for concatenation and it obviously doesn't suit us well.
How to overcome this issue ? Use double quotes to call an variable/function names in Python in ObjectScript code.
Example:
Class Article.PEP8Example Extends %RegisteredObject
{
ClassMethod Run()
{
Set sys = ##class(%SYS.Python).Import("sys")
do sys.path.append("/irisdev/app/src/python/article")
set pep8Example = ##class(%SYS.Python).Import("pep8_example")
do pep8Example."my_function"() // Notice the double quotes around the function name
}
}
This will call the my_function function in the pep8_example.py file, which is defined as follows:
# src/python/article/pep8_example.py
def my_function():
print("Hello, World!")
When you run the Run method of the Article.PEP8Example class, it will output:
iris session iris -U IRISAPP '##class(Article.PEP8Example).Run()'
Hello, World!
That's it!
I am trying to create users who only have `%SQL` Role for the INSTANCE. But I am unable to find any documentation on the `Security.Users` class.
See:
// Instantiate the Security.Users objectSet userObj = ##class(Security.Users).%New()// Set the username and passwordSet userObj.Name = userNameSet userObj.FullName = userFullNameSet userObj.Namespace = "USER"Set userObj.Roles = "%SQL" Set sc = userObj.ChangePassword(passwd)// Save the user to the databaseSet ss = userObj.%Save()
in order to do analysis on huge data volumes, it is better to take you data to a separate machine for analysis away from the operational machine, so trying to write huge globals or tables into files as is would take a huge space, what could be a solution or best practice ?..in python for instance, there is the pickling option (serializes data to byte string and saves it to a file) to save space, what could be best in object script ?
This will be an introduction to Python programming in the context of IRIS.
Before anything I will cover an important topic: How python works, this will help you understand some issues and limitations you may encounter when working with Python in IRIS.
All the articles and examples can be found in this git repository: iris-python-article
Python is an interpreted language, which means that the code is executed line by line at runtime even when you import a script.
What does this mean ? Let's take a look at the following code:
# introduction.py
def my_function():
print("Hello, World!")
my_function()
When you run this script, the Python interpreter reads the code line by line. It first defines the function my_function, and then it calls that function, which prints "Hello, World!" to the console.
Example of running the script directly:
python3 /irisdev/app/src/python/article/introduction.py
This will output:
Hello, World!
In an IRIS context, what will happen if we import this script ?
Class Article.Introduction Extends %RegisteredObject
{
ClassMethod Run()
{
Set sys = ##class(%SYS.Python).Import("sys")
do sys.path.append("/irisdev/app/src/python/article")
do ##class(%SYS.Python).Import("introduction")
}
}
Let's run it:
iris session iris -U IRISAPP '##class(Article.Introduction).Run()'
You will see the output:
Hello, World!
This is because the Python interpreter imports the code by interpreting it, first it defines the function and then calls it, just like it would if you ran the script directly but you are not running you are importing it.
⚠️ Important Note: If you import the script without calling the function, nothing will happen. The function is defined, but it won't execute until you explicitly call it.
Did you get it? The Python interpreter executes the code in the file, and if you don't call the function, it won't run.
Example of importing without calling:
# introduction1.py
def my_function():
print("Hello, World!")
Let's run it in an python interpreter:
python3 /irisdev/app/src/python/article/introduction1.py
Output:
# No output, because the function is defined but not called
In an IRIS context, if you import this script:
Class Article.Introduction1 Extends %RegisteredObject
{
ClassMethod Run()
{
Set sys = ##class(%SYS.Python).Import("sys")
do sys.path.append("/irisdev/app/src/python/article")
do ##class(%SYS.Python).Import("introduction1")
}
}
Let's run it:
iris session iris -U IRISAPP '##class(Article.Introduction1).Run()'
You will see no output, because the function is defined but not called.
🤯 Why this subtlety is important ?
When you import a Python script, the Python interpreter caches the imported script. This means that if you import the same script again, it will not re-execute the code in that script, but will use the cached version.
Demonstration by example:
Let's reuse the introduction.py script:
# introduction.py
def my_function():
print("Hello, World!")
my_function()
Now, same thing let's reuse the Article.Introduction class:
Class Article.Introduction Extends %RegisteredObject
{
ClassMethod Run()
{
Set sys = ##class(%SYS.Python).Import("sys")
do sys.path.append("/irisdev/app/src/python/article")
do ##class(%SYS.Python).Import("introduction")
}
}
But now, we will be running it twice in a row in the same IRIS session:
iris session iris -U IRISAPP
IRISAPP>do ##class(Article.Introduction).Run()
Hello, World!
IRISAPP>do ##class(Article.Introduction).Run()
IRISAPP>
🤯 What the heck ?
Yes, Hello, World! is printed only once !
⚠️ Your imported script is cached. This means if you change the script after importing it, the changes will not be reflected until you change the IRIS session.
This is even true if you use the language tag python in IRIS:
Class Article.Introduction2 Extends %RegisteredObject
{
ClassMethod Run() [ Language = python ]
{
import os
if not hasattr(os, 'foo'):
os.foo = "bar"
else:
print("os.foo already exists:", os.foo)
}
}
Let's run it:
iris session iris -U IRISAPP
IRISAPP>do ##class(Article.Introduction2).Run()
IRISAPP>do ##class(Article.Introduction2).Run()
os.foo already exists: bar
OMG, the os module is cached, and the foo attribute is not redefined to non existing.
I hope this introduction helped you understand why when you work with Python in IRIS, you may encounter some unexpected behaviors, especially when it comes to importing scripts and caching.
Takeway, when working with Python in IRIS:
Wait ! It doesn't make sense, if you say that when you import a script, it's cached. Why when I work with the language tag = python, when I change the script, it works without changing the IRIS session?
Good question, this is because the language tag is built in a way that everytime you run it, it will read the script again and execute it line by line as it was new lines in an native Python interpreter, language tag doesn't import the script, it just executes it as if you were running it directly in a Python interpreter without restarting it.
Example:
Class Article.Introduction2 Extends %RegisteredObject
{
ClassMethod Run() [ Language = python ]
{
import os
if not hasattr(os, 'foo'):
os.foo = "bar"
else:
print("os.foo already exists:", os.foo)
}
}
Let's run it:
iris session iris -U IRISAPP
IRISAPP>do ##class(Article.Introduction2).Run()
IRISAPP>do ##class(Article.Introduction2).Run()
os.foo already exists: bar
In a python interpreter it will look like this:
import os
if not hasattr(os, 'foo'):
os.foo = "bar"
else:
print("os.foo already exists:", os.foo)
import os
if not hasattr(os, 'foo'):
os.foo = "bar"
else:
print("os.foo already exists:", os.foo)
Output:
os.foo already exists: bar # only printed once
Make sense now?
Dear community, I have a confession to make. I have not gotten over Zen yet. Alas, all good things must come to an EOF, so I am currently learning about Angular. I am working on proving to myself that with the right back end and Angular components, I can deliver to myself and my team a very Zen-like experience in this environment. Since this is my first attempt, here is a fair warning: I will be providing some rather large code samples before discussing them. Please warm up your mouse and hand for extensive upcoming scrolling! Also, a note on the code snippets: many of them are labeled
I have been struggling sometime with trying to take a FHIR Bundle Response, extract the "entry.resourceType", extract the MRN and Name from the Patient FHIR Response...
Going through learning.intersystems.com, it suggested that I try using fhirPathAPI to parse and search my response for certain values, however I am not sure my syntax is correct. Using the AI code, it suggested to set my tree = "Bundle.entry.resource.resourceType"
Hi Developers!
There is a free ObjectScriptQuality tool for ObjectScript developers who upload solutions on GitHub. This tool helps developers validate ObjectScript code using a variety of rules, based on common code errors.
There are currently 16 rules in this tool, but there are definitely many more rules to consider when testing ObjectScript code.
Could you suggest any other rules to add to this tool?
Hello my friends,
I have a problem with Objectscript, why the value of address become like this ?
everything works fine except the Address,
this is my code, do I need something to make this into real address ? should I put something in my code ?
set paper=obj.PAADMPAPMIDR.PAPMIPAPERDR
if '$isobject(paper) continue
set Address=paper.PAPERStName
thank you for your help
Best Regards,
Steven Henry
Hello my friends,
I have a bit problem with date format, I need to display like this DD-MM-YYYY
I've put the objectscript like this : set DOB=$zd(paper.PAPERDob,15)
and the result is
Why It cannot show the full year, I mean why 99 or 95 why not 1999 or 1995 ?
Thank You
Best Regards,
Steven Henry
Do not let the title of this article confuse you; we are not planning to take the InterSystems staff out to a fine Italian restaurant. Instead, this article will cover the principles of working with date and time data types in IRIS. When we use these data types, we should be aware of three different conversion issues:
I have built a REST operation to submit a JSON Request Body, and in the JSON Response Object, I need to pull out certain values like pureID, portalURL, and under the identifiers array the ClassifiedID that has a term."en_US" = "Scopus Author ID"
I am writing this post primarily to gather an informal consensus on how developers are using Python in conjunction with IRIS, so please respond to the poll at the end of this article! In the body of the article, I'll give some background on each choice provided, as well as the advantages for each, but feel free to skim over it and just respond to the poll.
Hi fellow developers!
Curious if you guys use CreatedAt and LastUpdated properties in your classes?
Created to stamp when the record was created and LastUpdated when it was last updated. Where it can be useful - almost everywhere )) I find it convenient in records sorting (e.g. by creation or last update), in sync (with other systems), and so on, for better analytics.
Do you use it all the time for all the classes?
If don't, why not? What do you use instead?
What property type do you use - %TimeStamp? %DateTime?
What is the best practice to have CreatedAt filled automatically during creation and LastUpdated on every successful save (guess it could be in %OnSave)?
Please share your experience /thoughts?
The below code is not working. its unable retrieve Record count and merge files
Class Util
{
ClassMethod zPyRecordCount(inputfile) As %Integer [ Language = python ]
{
import pandas as pd
import iris
import io
try:
df = pd.read_csv(inputfile, sep='|')
recordcount=len(df.index)
sys.stdout.write(len(df.index))
return recordcount
except Exception as e:
return 0
}
ClassMethod zPymergefiles(file1, file2, outputfilename) As %Boolean [ Language = python ]
{
import pandas as pd
import iris
import io
try:
Hi noble devs!
Just building a simple frontend->JSON->IRIS backend story, and figured that IRIS while importing via %JSON.Adaptor wants JSON fields to match property names, meaning even should match the case. Like:
{ name: "John",
surname: "Doe"}will have issues while saving the dynamic object to a class Sample.Person with:
Class Sample.Person Extends (%Persistent, %JSON.Adaptor)
{
Property Name: %Sting;Property Surname: %String;
}As soon as the case is not the same...
InterSystems IRIS allows you to build REST APIs using ObjectScript classes and the %CSP.REST framework. This enables the development of modern services to expose data for web apps, mobile apps, or system integrations.
In this article, you'll learn how to create a basic REST API in InterSystems IRIS, including:
GET and POST methodsDemo.ProductoHi all,
We're developing a medical appointment app that connects doctors' schedules to an appointment provider.
The provider is returning us the appointment in the following format:
Thu Jul 03 08:20:00 CEST 2025
It means, 03 july 2025 at 08:20:00 Central European Summer Time (UTC+2)
But we need the following format:
2025-07-03 08:20:00+02:00
Is there any option to convert zone time code (CEST) to a UTC+x ?
How to convert zone time code (CEST, CET, ET, EDT, etc..) in its zone time in UTC (UTC+2, UTC+1, UTC-5, etc..) ?
Best regards
This can be achieved by using the CSV() procedure of the %SQL.Util.Procedures class.
Below is an example of usage code. (Assuming that the file test.csv is in c:\temp.)
Hello,
I have a problem generating QR code in Caché now.
After executing the code
set Status=##Class(%SYS.QRCode).GenerateImage(P0,,.DataURI)
(variable P0 contains data for QR code)
an error is displayed now:
"<NOTOPEN>zGenerate+27^%SYS.QRCode.1",,,,,,,,
("$^zGenerate+27^%SYS.QRCode.1 +1","$^zGenerateImage+4^%SYS.QRCode.1 +1"
This error occurs only on two servers, on the others the code works fine.
When calling the method, I do not specify any external file that should be opened.
Thank you for the answers.
Having been inspired with Shared code execution speed question/discussion, I dare to ask another one which is annoying me and my colleagues for several weeks.
We have a routine called Lib that comprises 200 $$-functions of 1500 code lines total. It was noticed that after calling _any_ function of another rather big routine (1900 functions, 32000 lines) the next call of $$someFunction^Lib(x) is getting 10-20% slower than previous call of the same function. This effect doesn't depend on:
Embedded Python has been around for a while. You probably followed the tutorials and learned about it. However, if you've tried to combine Python and ObjectScript in real development work, you probably ran into situations where you get an error message like this:
USER>Do##class(MyClass).SomeMethod() ERROR #5002: ObjectScript error: <PYTHON EXCEPTION> *<class 'ZeroDivisionError'>: division by zero
Hey everyone,
I'm diving deeper into Caché ObjectScript and would love to open a discussion around the most useful tips, tricks, and best practices you’ve learned or discovered while working with it.
Whether you're an experienced developer or just getting started, ObjectScript has its own set of quirks and powerful features—some well-documented, others hidden gems. I’m looking to compile a helpful set of ideas from the community.
Some areas I’m especially interested in: