Nueva publicación

Encontrar

Artículo
· 22 ene, 2026 Lectura de 5 min

IRIS Cloud Document - Beginner Guide & Sample : Part I - Intro and Quick Tour

If you already know Java (or .Net) and perhaps also have used other document databases (or looking for one), but you are new to the InterSystems world, this post should help you.

InterSystems IRIS Cloud Document is a fully managed document database that lets you store JSON documents and query them with familiar SQL syntax, delivered as a cloud service managed by InterSystems.

In this article pair I’ll walk you through:

  • Part I - Intro and Quick Tour (this article)
    • What is it?
    • Spinning up an InterSystems IRIS Cloud Document deployment
    • Taking a quick tour of the service via the service UI
  • Part II - Sample (Dockerized) Java App (the next article)
    • Grabbing the connection details and TLS certificate
    • Reviewing a simple Java sample that creates a collection, inserts documents, and queries them
    • Setting up and running the Java (Dockerized) end‑to‑end sample

The goal is to give you a smooth “first run” experience.

1. What is InterSystems IRIS Cloud Document?

Cloud Document is a document database service built on top of the InterSystems IRIS data platform, exposed as a managed cloud service. You work with JSON documents stored in Collections, then query them using SQL, or through language‑specific drivers (Java or .NET).

Conceptually:

  • A Document is a JSON object or array.
  • A Collection is a logical container for documents and gives you APIs for insert/get/update/delete/query.
  • Under the hood it’s the same engine that powers other IRIS data services, so you can use SQL to query document data if and when you need it.

2. Spinning up a deployment

You manage Cloud Document through the InterSystems Cloud Services Portal.

High‑level steps:

2.1 Create a deployment

  • Log into the Cloud Services Portal.
  • [By the way you need a Subscription to the service - but this is outside the scope of this article, as this is more of a commercial topic. For more details you can see our Services page Docs and the related AWS Marketplace service listing page]
  • Create a new IRIS Cloud Document deployment.
  • Choose region, name, etc., and let the deployment finish provisioning.

For example:

 

Here's a short video demonstrating this:

3. A quick tour: upload JSON, import into a collection, browse and query

The Cloud Document web console gives you a nice “zero code” way to get familiar with the service. The flow looks like this: upload a JSON file → import it into a collection → browse with the Collection Browser → run some SQL.

You’ll find these pages under your deployment’s web UI; this page from the Docs walks through the same steps.

3.1 Upload a sample JSON file

Create a small colors.json file locally, for example:

 
Colors JSON

In the Cloud Document deployment UI:

  1. Go to the Add and Manage Files  page.
  2. Use the Upload button and select your colors.json file.

The file must have an object or an array at the top level, which our example does.

3.2 Import the JSON into a collection

Now import the uploaded file into a Cloud Document collection:

  1. Navigate to the Collection Import page in the deployment UI.
  2. Choose your uploaded colors.json via Select file.
  3. For Collection, either:
    • pick an existing collection, or
    • choose (Add new collection) and enter something like colors(Here I clicked Preview, which shows the contents, and summarizes that upon import 3 documents will be added)
  4. Click Import.

The service will parse the JSON and write each object into the colors collection. If your file is large, this may take a bit longer; for three tiny objects it’s almost instant.

You should see a green popup message saying 3 documents:

[In case you get a red popup message, indicating there was some error, this might be because this is your first import, and the service "backend" is still "warming up". Looking at the network trace you might see something like this:

... https response error StatusCode: 409, RequestID: ... , api error CodeArtifactUserPendingException: ERROR: Lambda is initializing your function. It will be ready to invoke shortly.

And indeed you can ignore this, wait a little, and try again shortly after.]

3.3 Explore the data with the Collection Browser

Once you’ve imported, go to the Collection Browser page and select the colors collection. You should see each document displayed as JSON.

Things to try:

  • Click on individual documents (via the Previous and Next buttons) and inspect their JSON.
  • Confirm that all the objects from your file are present.
  • Notice that collections are just logical groupings; you can have multiple collections with very different shapes of documents.

This browser is a good way to sanity-check what’s in your deployment without writing any code.

3.4 Run a simple SQL query

Cloud Document documents live in collections, but you can query them via SQL using JSON_TABLE (see Docs) to project JSON data into a tabular shape. In the deployment UI, go to the SQL Query Tools page and run queries such as:

SELECT name, rgb, hex
FROM JSON_TABLE(colors FORMAT COLLECTION)

Or for example using more functionality of JSON_TABLE:

SELECT c.name, c.hex 
FROM JSON_TABLE( 'colors', 
   '$[*]' COLUMNS ( 
         name VARCHAR(50) PATH '$.name', 
         hex VARCHAR(10) PATH '$.hex'
        ) 
  ) AS c 
ORDER BY c.name

That’s the core pattern: load JSON into a collection, browse it as documents, and query it via SQL when you want to slice or join it.

Here's a short video demonstrating this:

Now we can move on to the next article, there we'll review and explain running a Java app, connecting to our Cloud Service, and interacting with it.

Comentarios (0)1
Inicie sesión o regístrese para continuar
Resumen
· 22 ene, 2026

Resumen de la Comunidad de Desarrolladores, diciembre 2025

Hola y bienvenidos al boletín de la comunidad de desarrolladores diciembre 2025.
Estadísticas generales
✓ publicaciones nuevas:
 11 artículos
 7 anuncios
 2 nuevas preguntas
3 nuevos miembros se unieron en diciembre
2,332 contenidos publicados de forma constante
870 miembros se unieron de forma constante
Publicaciones populares
Autores populares
Artículos
#InterSystems IRIS
#Comunidad de Desarrolladores Oficial
#Otro
Anuncios
Preguntas
diciembre, 2025Month at a GlanceInterSystems Developer Community
Artículo
· 22 ene, 2026 Lectura de 1 min

Destaque do FHIR 2024.3 - Novos Modificadores de Busca FHIR Suportados e Parâmetro de Resultado de Busca

O InterSystems IRIS for Health v2024.3 já está disponível como Developer Preview há algum tempo, e eu gostaria de destacar o novo suporte relacionado à Busca FHIR (FHIR Search) que foi introduzido.

Foram adicionados suportes a dois Modificadores -

Estes permitirão consultas de busca mais flexíveis, sofisticadas e ricas.

E um Parâmetro de Resultado de Busca -

Isso permitirá resultados mais compactos (e potencialmente mais eficientes).

 

Veja também as Notas de Lançamento (Release Notes) relacionadas.

Comentarios (0)1
Inicie sesión o regístrese para continuar
Anuncio
· 22 ene, 2026

Help Shape the Future of ObjectScript Development

Hi Community,

We’re excited to invite you to take part in shaping the next generation of ObjectScript development tools. We’re working on an AI-powered ObjectScript coding assistant designed specifically for IRIS developers. Not a generic AI adapted for ObjectScript, but a solution built from the ground up to understand ObjectScript idioms, IRIS APIs, interoperability productions, and real-world developer workflows.

To make sure we build something truly useful, we need your input.

👉 ObjectScript Coder Agent Developer Survey 👈

The survey takes about 5 minutes and covers topics such as:

  • Your role and experience level
  • Current pain points and workflows
  • What features matter most (code generation, debugging, learning support, and more)
  • Where and how you’d like to use such a tool

The survey is open to developers at all levels of ObjectScript experience.

What’s next?

  • Aggregated results will be shared with the community
  • Interested participants may receive early beta invitations
  • Regular progress updates as development moves forward

Your feedback will directly influence what we build first and how it works.

If you have questions, feel free to comment below or reach out directly at thomas.dyar@intersystems.com.

Thank you for helping us build better tools for the ObjectScript community. We’re looking forward to your input!

Comentarios (0)3
Inicie sesión o regístrese para continuar
Artículo
· 22 ene, 2026 Lectura de 7 min

Getting started with OAuth in your Web Apps

This article is intended as a beginner level article for people that want to learn how to use OAuth2 in their web applications natively.

There is an accompanying video/demo that may be helpful here: 

 

and you can reproduce this locally with the Open Exchange application attached.

OAuth2 as a native authentication type for web applications

OAuth (Open Authorization) 2.0 is a standard way to let one application call another application’s API without sharing a username and password. Instead of sending credentials on every request, the client sends an access token (typically in an Authorization: Bearer ... header).

OAuth2 focuses on authorization (what the client is allowed to do). If you also need user login and identity claims, OAuth2 is commonly paired with OpenID Connect (OIDC) — but in this article we’ll stay focused on OAuth2 access tokens and scopes.

If you want a quick refresher, this short video is a good overview: OAuth 2.0 An Overview.

The problem OAuth2 solves (with a simple IRIS example)

Assume IRIS hosts a small REST API for a bank account ACCT-1 under /bank:

GET
/bank/checkbalance

{
  "dollars": 5
}

POST
/bank/transfer

{
  "toAccount": "ACCT-2",
  "dollars": 2
}

Now suppose you want to allow a third-party app to monitor your balance. It should be allowed to call /checkbalance, but it should not be allowed to call /transfer.

This is where OAuth2 fits well: instead of giving the third-party app your IRIS username/password, you grant it limited access via a token. That token can be:

  • Scoped (e.g., “read balance” but not “transfer funds”)
  • Time-limited (tokens expire)
  • Revocable (you can withdraw access later)

What’s new in IRIS

Starting in IRIS 2025.2, OAuth2 can be selected as a native authentication method for Web Applications — so enabling an OAuth2-protected web app is no longer a “DIY” exercise.

Concretely, IRIS can validate an incoming access token for a CSP/Web Application request and then establish a user context (username + roles) based on that token, just like other authentication types do.

(For reference on the older, more manual approach, see @Daniel Kutac’s excellent series of articles.)

The Characters

OAuth has a few “characters”:

  • Resource Owner (the user/owner of the bank account)
  • Client (the third-party app; in this demo we use Postman as the client)
  • Authorization Server (Keycloak; authenticates the user & authorizes the request, deciding what scopes the client can receive, and issues the token)
  • Resource Server (IRIS; hosts /myBankInfo, validates the token, and enforces what the token is allowed to do). The third-party app never sees your IRIS password — it presents a token, and IRIS makes the allow/deny decision.

Step 0: Prerequisites (avoid issuer / hostname issues)

Note: This demo uses HTTP to keep setup simple. In production you should use HTTPS (and real certificates), otherwise tokens and sessions can be intercepted.

This Open Exchange demo runs multiple Docker containers. One important rule to remember is:

  • localhost on your host is not the same as localhost inside a container.

OAuth token validation checks the token’s issuer claim (iss). If Keycloak issues a token with an issuer like http://localhost:8080/... but IRIS discovers/validates it using http://keycloak:8080/..., IRIS will reject the token because those issuers do not match.

To keep the issuer stable, this demo uses the hostname keycloak consistently from both the host and the containers.

On Windows, edit: C:\Windows\System32\drivers\etc\hosts and add:

127.0.0.1 keycloak

On Linux/Mac, edit /etc/hosts and add the same line (you’ll typically need sudo).

From this point on, use http://keycloak:8080 (not http://localhost:8080) when configuring Postman and IRIS.

Step 1: Configure the Authorization Server (Keycloak)

For the demo, the Authorization Server is Keycloak and it is already prepared for this use case (realm, clients, users, scopes). No work is needed here.

You can access the Keycloak admin console at http://keycloak:8080/keycloak/admin/master/console/ (username/password admin/admin).

Explaining Keycloak itself is not in the scope for this article, but if you would like to read more you can find the docs here.

Step 2: Tell IRIS who the Authorization Server is

In the Management Portal, go to:

System Administration > Security > OAuth 2.0 > Client

Click Create Server Description, set the Issuer URL (in the demo: http://keycloak:8080/keycloak/realms/bank), then click Discover and Save. IRIS will pull the endpoints and metadata it needs from the server (authorization endpoint, token endpoint, JWKS URI, etc.).

Step 3: Configure IRIS as the Resource Server

Next, create a Resource Server entry so IRIS can validate tokens and enforce permissions:

Click Create Resource Server:

Fill in the details of your resource server, for example:

Name: IRIS Bank Resource Server

Server Definition: http://keycloak:8080/keycloak/realms/bank

Audiences: bank-demo, bank-monitor

What is “Audience”? The token’s audience (aud) is the “intended recipient” of the token. By configuring audiences here, you are telling IRIS to accept only tokens that were issued for this API (i.e., tokens whose aud matches one of these values).

Click save.

We will set the Authenticator class in the next step. Note that this is not strictly necessary; you could use the %OAuth2.ResourceServer.SimpleAuthenticator in your own implementations and just fill in what token property should be attributed to the role and user. However, for the sake of completeness we will create a simple custom authenticator class.

Step 4: Create your Authenticator Class

What should be authenticated? We will create a simple class Bank.Authenticator that maps token claims/scopes into an IRIS username and IRIS roles.

This is the key step that lets IRIS enforce “read-only” vs “transfer” behavior:

  • The token’s scopes become IRIS roles.
  • Your web application (and/or your REST endpoints) can require those roles.

In other words, this is what makes /checkbalance  succeed for a “monitor” token while /transfer returns 403 Forbidden unless the token includes the transfer scope.

Class Bank.Authenticator Extends %OAuth2.ResourceServer.Authenticator
{

// Check if scopeStr is in scope
ClassMethod HasScope(scopeStr As %String, scope As %String) As %Boolean
{
    Quit ((" "_scopeStr_" ") [ (" "_scope_" "))
}

Method Authenticate(claims As %DynamicObject, oidc As %Boolean, Output properties As %String) As %Status
{
    // Map token -> IRIS username
    Set properties("Username") = claims."preferred_username"
    // Map scopes -> IRIS roles
    Set scopeStr = claims.scope
    Set roles = ""
    If ..HasScope(scopeStr,"bank.balance.read") {
        Set roles = roles_",BankBalanceRead"
    }
    If ..HasScope(scopeStr,"bank.transfer.write") {
        Set roles = roles_",BankTransferWrite"
    }

    If $Extract(roles,1)="," Set roles=$Extract(roles,2,*)
    
    Set properties("Roles") = roles_",%DB_USER"
    Quit $$$OK
}

}

Once you compile the class you will be able to set your authenticator class in your resource server:

Save your resource server.

Step 5: Enable OAuth2 on the Web Application

Before enabling OAuth2 for a web app, you must enable it at the System level:

System Administration > Security > System Security > Authentication/Web Session Options

Finally, on your Web Application definition, select OAuth2 as an allowed authentication method. The dispatch class will check that the client has the necessary roles.

Step 6: Test it out

At this point, requests to your application can be authorized based on the presented token — so you can allow read-only access to /checkbalance while denying access to /transfer using the OAuth2 framework.

Load the Postman collection and environment. There are two demo users/passwords to have in mind: user1/123 and user2/123.

User 1 has account ACCT-1, User 2 has account ACCT-2.

In Postman, on Authorization click Get New Access Token:

This brings up the login screen for our Authorization Server:

Log in with user1/123. Click proceed and then click Use Token.

Send your GET to /checkbalance and you should see it return 5 dollars:

Clear cookies and try logging in with user 2 and you should see them have 0 dollars in their balance.

Now get a token for user 1 and try to transfer user 2 a couple dollars. It should fail with 403 Forbidden as this “app” does not have the required scopes (it is only monitoring the bank account and should not be able to transfer money).

Try again with requests 3 and 4 which simulate a client with full access and you should be able to both check your balance and transfer funds.

The new OAuth2 native authentication type ensures it is intuitive to keep your web applications safe, and after all, that's what the I in IRIS is all about.

Comentarios (0)1
Inicie sesión o regístrese para continuar