Import deepsee(.dfi) files via IPM

Question

Question

Ashok Kumar T · Dec 15, 2025

#InterSystems Package Manager (IPM) #XML #InterSystems IRIS BI (DeepSee) #InterSystems IRIS for Health

Hello Community,

What is the correct way to import and compile .dfi files when using zpm load? Do .dfi files need to be defined in module.xml?

I have code that imports the .dfi file successfully; however, when I run
zpm "load /home/irisowner/dev/ -v"

I get the message: Unknown file type. Skipping file: .pivot.DFI

    zpm "install isc-dev"
    do ##class(dev.code).workdir(dir)
    do ##class(dev.code).import("*.DFI")

Thank you!

Product version: IRIS 2025.1

$ZV: IRIS for UNIX (Ubuntu Server LTS for x86-64 Containers) 2025.1 (Build 223U) Tue Mar 11 2025 18:23:31 EDT

Discussion (30)6

Log in or sign up to continue

score 0 · Answer 1 · 2025-12-16T03:35:18-05:00

No idea about zpm.
Just a guess: if not listed or in a PKG it won't be touched
BUT this loads and compiles it

set tSC=$system.OBJ.Import(fileref,"ck")

score 0 · Answer 2 · 2025-12-16T08:34:15-05:00

I take the approach of adding my .DFI items to a class that extends %DeepSee.UserLibrary.Container following

Creating a Business Intelligence Container Class

as this allows me to treat like any other class.

This means I can

commit to the source control repository just like any other class
deploy like any other class
include the Container class in my module definition to be delivered via ZPM/IPM

This capability has been around since 2018 +/-.

score 0 · Answer 3 · 2025-12-17T12:00:46-05:00

Ashok Kumar T · Dec 17, 2025

Thank you @Stephen Canzano
I'll try myself.

0 0

score 0 · Answer 4 · 2025-12-20T04:40:30-05:00

The only "caveat" of the approach is that you should put all of the pivots and dashboards into one big class container. Even you have 100+ of them.

It's like, "let's put all the classes into one big XML and store it in the repo in one file". It's OK for import/export, but not ideal for source control.

score 0 · Answer 5 · 2025-12-16T15:12:36-05:00

Hi Ashok!

Yes, you can use IPM to support DFI files.

"Lazy", aka "dirty" way - introduce the following resource:

<Resource Name="*.DFI" />

like here, which will package everything you have in a src/dfi folder. Convenient but not optimal and can introduce problems while working with more than one IRIS BI packages.

in this case resource will import all the 100+ DFIs (pivots, dashboards) into IRIS (via load command) and package/publish then:

Don't ask me, why DFI is an XML in fact.

score 1 · Answer 6 · 2025-12-16T15:17:17-05:00

You may ask: how to export the file?

There is a special "helper" package "isc dev", once installed via:

zpm "install isc-dev"

and set up then as:

do ##class(dev.code).workdir("/home/irisowner/dev/src")

it will allow at any moment to export all the DFI at once into your dev folder with the command:

d ##class(dev.code).export("*.DFI")

score 0 · Answer 7 · 2025-12-17T10:10:46-05:00

Hi @Evgeny Shvarov
Thank you for the details. So, Do I need to keep the files in .xml format in my repo not in .dfi

score 0 · Answer 8 · 2025-12-17T10:22:07-05:00

I'd say xml as it's been working well with IPM packaging and standard import/export.

But if dfi is working for you it'd be great to hear! I kind of like .dfi more as it's more clear what the file is about. But xml is fine too.

score 0 · Answer 9 · 2025-12-17T11:20:27-05:00

Thank you! ZPM load actually skip the .dfi file and eventually failed with " ERROR! Unable to import file '/home/irisowner/dev/Test/Test-UTest.pivot.DFI' as this is not a supported type"

score 1 · Answer 10 · 2025-12-19T22:36:16-05:00

There is a refined version of the app isc-dev: iris-bi-utils. The version is more organize, all methods placed in there categories and it has cool and memorable name 😁.

score 0 · Answer 11 · 2025-12-20T04:30:47-05:00

Evgeny Shvarov · Dec 20, 2025

Thank you, @Dmitrij Vladimirov

0 0

score 0 · Answer 12 · 2025-12-16T15:53:44-05:00

And here is an example of "proper" using DFI resources - OEX module, Github.

There is one dashboard and two pivots here:

Git-source-control "supports" editing in the UI and exporting to files, but it is quite "buggy" - I hope @Timothy Leavitt and Co will introduce 100% support of DFI someday. Today I prefer to use "isc-dev" and export all the DFI from the namespace into the dev folder to commit changes to the individual DFI files.

But still, the question for the iPM/ObjectScript VSCode team is why the Other section (server-side viewer in VSCode ObjectScript) exports DFI in a different format, which cannot be imported later with the system import method, and thus is not being imported by IPM. Maybe @Brett Saviano can comment here:

Also, why is the naming of resources so complex (you need to use "-" as the folder delimiter and follow this in folder structures.

But it works somehow.

score 1 · Answer 13 · 2025-12-16T16:49:21-05:00

@Evgeny Shvarov The Atelier REST API used by VS Code uses the same document representation as $SYSTEM.OBJ.ExportUDL(). It has no trouble saving files that are sent to it in this format. If $SYSTEM.OBJ.Import/ImportDir/Load() can't import that format then I believe that's a bug that should be reported to development.

score 0 · Answer 14 · 2025-12-17T02:36:44-05:00

Hi @Brett Saviano !

I double checked the export format - the format is the same now and is supported both in IPM and VSCode ObjectScript.

The only issue left is file naming: Atelier REST API exports DFI file names with dFI extension as:

Potatos-AnnualPotatos.dashboard.DFI

at the same time IPM can consume DFI resources if they are presented as XML (tested in 0.10.4), e.g.:

Potatos/AnnualPotatos.dashboard.xml

Inviting @Pravin Barton also, maybe there are plans to do something with this in the future.

And it exports files with "-" as a folder delimeter. Imagine if you have 100+pivots and dashboards in folders - in the code repository, they all will be in one folder with 100+ files with "-" as delimiters. Doesn't sound like a convenient approach.

It's like ObjectScript code files will be named as:

/src/package-subpackage-class.cls

and all reside in one folder, instead of being distributed in packages as folders, as it is working now:

src/package/subpackage/class.cls

@Brett Saviano - hope we could fix this too in the future.

score 0 · Answer 15 · 2025-12-17T13:47:14-05:00

Just can confirm that it works for me with a correct structure
.../src
       /DFI
           /first.DFI
           /next.DFI
           /andSoOn.DFI

And in module.xml the relevant part looks like this

      <Packaging>module</Packaging>
      <SourcesRoot>src</SourcesRoot>
      <Resource Name="DFI.PKG"/>

BINGO

score 0 · Answer 16 · 2025-12-17T16:44:06-05:00

Evgeny Shvarov · Dec 17, 2025

no way. Could you please share the repo?

0 0

score 1 · Answer 17 · 2025-12-17T18:02:51-05:00

here is it - ~~work in progress~~ ZPM load DFI
~~Analytics need manual enable, cube to build still manually~~
BUT:
all DFI are all there (checked with Studio) and working immedeately

score 0 · Answer 18 · 2025-12-19T07:28:46-05:00

Like the minimalistic setup, but this doesn't work on mac:

 12/19/25-12:27:01:978 (467) 0 [Utility.Event] Initializing Interoperability during system startup
iris-1  | [INFO] ...started InterSystems IRIS instance IRIS
iris-1  | [INFO] Executing command /docker-entrypoint.sh iris-after-start '/ext/ascript.sh'...
iris-1  | [ERROR] /docker-entrypoint.sh: line 196: /ext/ascript.sh: Permission denied
iris-1  | [ERROR] Command "/docker-entrypoint.sh iris-after-start '/ext/ascript.sh'" exited with status 32256
iris-1  | [FATAL] Error executing post-startup command
iris-1  | [INFO] Shutting down InterSystems IRIS instance IRIS...

score 0 · Answer 19 · 2025-12-19T07:46:01-05:00

It indeed works! After providing proper (for Mac) Dockerfile and Docker-compose.yml, and adding DSW, here is what I'm getting:

score 0 · Answer 20 · 2025-12-19T07:58:12-05:00

Robert Cemper · Dec 19, 2025

GREAT,
So the DFI worked. I never have touched MAC until now,

0 0

score 0 · Answer 21 · 2025-12-19T08:55:47-05:00

I think what've found is a "hack", or side-effect. Because of ZX.PKG resource line IPM imports "everything" from /src/ZX folder, inlcuding dfi files which happen to be there.

But it's OK. I wonder, if there will be no classes in ZX, or if you include another folder ZY which include only DFI documents inside, will IPM import those as well?

score 0 · Answer 22 · 2025-12-19T09:21:36-05:00

to me *.PKG is imported by $system.OBJ.LoadDir(...) whaever the file name is
one file contained a %ZX.* class.
That one required manual compilation as it didn't match the ZX.* pack
a real class, no DFI

score 0 · Answer 23 · 2025-12-19T11:59:31-05:00

Sounds like that.

Actually, I tried with another proejct and failed going with PKG approach, as DFI are being exported in a shorter form for me, .e.g.:

<?xml version="1.0"?>

<dashboard xmlns="http://www.intersystems.com/deepsee/library" name="AnnualPotatos" folderName="" title="Annual Potato Analytics" description="" keywords="" owner="" shared="true" public="true" locked="false" resource="" timeCreated="2025-08-26T23:29:13.2Z" createdBy="SuperUser" category="" bookCover="" scheme="" worklistCount="2" snapTo="true" snapGrid="true" gridRows="10" gridCols="10" canResize="true" canModify="true" showTitleBar="true" titleBarOpacity="" titleBarColor="" selectedTitleBarOpacity="" selectedTitleBarColor="" titleBarTextColor="" selectedTitleBarTextColor="" titleBarFont="" companyName="" companyLogo="" companyStyle="" backgroundColor="white" backgroundImage="none" backgroundRepeat="no-repeat" backgroundSize="100% 100%" backgroundOpacity="1" widgetBorders="1px solid #F0F0F0" widgetBordersSwitch="edit" widgetBordersColor="#F0F0F0" widgetBordersStyle="solid" widgetBordersWidth="1" widgetBordersToggle="true">

<widget name="Widget2" type="pivot" subtype="comboChart" subtypeClass="comboChart" title="Potato Sales and Import, Tonnes" dataSource="Potatos/Yearly.pivot" dataLink="" drillDownDataSource="" width="200" height="200" sidebarContent="" showSidebar="false" sidebarWidth="" maximized="false" homeRowL="0" homeColL="0" colSpanL="7" rowSpanL="7" showToolbar="true" showToolbarBottomBorder="true" showToolbarOnlyWhenMaximized="false" colorToolbar="#F0F0F0" opacityToolbar="1" backgroundColor="#F0F0F0" opacity="1" theme="" dataColorList="">

<control name="" action="applyFilter" target="" targetProperty="[Country].[H1].[Country]" location="widget" type="auto" controlClass="" label="Country" title="" value="" text="" readOnly="false" valueList="" displayList="" activeWhen="">

<valueRequired>false</valueRequired>

</control>

<override name="comboChart">{legendVisible:'false',xAxis:{_type:'axis'},yAxisList:[{_type:'axis'}],seriesTypes:',bar',_type:'comboChart'}</override>

</widget>

</dashboard>

In your case there is also an export tag:

<?xml version="1.0"?>

<Export generator="IRIS" version="26" zv="IRIS for Windows (x86-64) 2024.3 (Build 217U)" ts="2025-09-21 16:49:04">



<dashboard xmlns="http://www.intersystems.com/deepsee/library" name="AnnualPotatos" folderName="Potatos" title="Annual Potato Analytics" description="" keywords="" owner="" shared="true" public="true" locked="false" resource="" timeCreated="2025-08-26T23:29:13.2Z" createdBy="SuperUser" category="" bookCover="" scheme="" worklistCount="2" snapTo="true" snapGrid="true" gridRows="10" gridCols="10" canResize="true" canModify="true" showTitleBar="true" titleBarOpacity="" titleBarColor="" selectedTitleBarOpacity="" selectedTitleBarColor="" titleBarTextColor="" selectedTitleBarTextColor="" titleBarFont="" companyName="" companyLogo="" companyStyle="" backgroundColor="white" backgroundImage="none" backgroundRepeat="no-repeat" backgroundSize="100% 100%" backgroundOpacity="1" widgetBorders="1px solid #F0F0F0" widgetBordersSwitch="edit" widgetBordersColor="#F0F0F0" widgetBordersStyle="solid" widgetBordersWidth="1" widgetBordersToggle="true">

<widget name="Widget2" type="pivot" subtype="comboChart" subtypeClass="comboChart" title="Potato Sales and Import, Tonnes" dataSource="Potatos/Yearly.pivot" dataLink="" drillDownDataSource="" width="200" height="200" sidebarContent="" showSidebar="false" sidebarWidth="" maximized="false" homeRowL="0" homeColL="0" colSpanL="7" rowSpanL="7" showToolbar="true" showToolbarBottomBorder="true" showToolbarOnlyWhenMaximized="false" colorToolbar="#F0F0F0" opacityToolbar="1" backgroundColor="#F0F0F0" opacity="1" theme="" dataColorList="">

<control name="" action="applyFilter" target="" targetProperty="[Country].[H1].[Country]" location="widget" type="auto" controlClass="" label="Country" title="" value="" text="" readOnly="false" valueList="" displayList="" activeWhen="">

<valueRequired>false</valueRequired>

</control>

<override name="comboChart">{legendVisible:'false',xAxis:{_type:'axis'},yAxisList:[{_type:'axis'}],seriesTypes:',bar',_type:'comboChart'}</override>

</widget>

</dashboard></Export>

And zpm load imports the latter one, but not the first type.

Also, if I save it in VSCode, it removes <export> tag as a result of compiling. But the same doesn't let it be imported via PKG approach.

score 0 · Answer 24 · 2025-12-19T16:21:16-05:00

Interesting observations.

My export came directly out of STUDIO.
InterSystems Studio Client 2024.1.0 Build 262
Server IRIS for Windows (x86-64) 2025.1 (Build 230.2U)

Simple right click + export ..... (+ Windows Directory).
Just straight, no flags, no anything extra

score 0 · Answer 25 · 2025-12-20T05:29:50-05:00

@Evgeny Shvarov you pointed me to the correct place
Did some checks using the most native approach.

 set sc=$system.OBJ.Import(file, . . . . .

Removing the Export Tag from the 2nd line in the 'hidden XML' names DFI

<Export generator="IRIS" version="26" zv="IRIS for Windows (x86-64) 2024.3 (Build 217U)" ts="2025-09-21 16:53:05">

ends with unknown flle type !!!

After re-insert of that Export Tag all import works perfect

might be necessary to teach VScode to add that tag

score 0 · Answer 26 · 2025-12-20T06:26:35-05:00

Yes.

It maybe a different thing: the format with <Export generator> is outdated and Studio together with LoadDir both support the outdated format and don't support the "new" one without the <Export> element, which is in Atelier API that VSCode is using (why do we still use this Atelier name? )

So, I'd better ask to support the new format, as the Export tag thing also has an annoying "feature" that it incudes date/time of export and this changes the file with every save/export even there were no changes.

score 0 · Answer 27 · 2025-12-19T07:57:52-05:00

Next is editing and control versioning in VS-Code.

DFI changes in VS-Code are not propagating to connected IRIS automatically after saving. @Brett Saviano - any hints how can this be set up?

In order to make changes in the Dashboard portal to be automatically reflected, one can use git-source-control. After the following lines:

USER> zpm "install git-source-control"

USER> do ##class(%Studio.SourceControl.Interface).SourceControlClassSet("SourceControl.Git.Extension")

changes made in Dashboard Portal editor are being exported into VSCode (into a file), but the location is wrong - git-source-control has created cls/ZXFree folder and dashboard.dfi

But I expected src/ZXfree.dashboard.DFI, as there is no Folder in a dashboard, just title="ZXFree"

@Pravin Barton , @Timothy Leavitt - could you please take a look?

score 0 · Answer 28 · 2025-12-19T08:06:57-05:00

Robert Cemper · Dec 19, 2025

I see.
This didn't happen for me as I just work from Studio

0 0

score 1 · Answer 29 · 2025-12-18T11:30:04-05:00

Robert Cemper · Dec 18, 2025

Updated init + load + build of cubes
2025....latest had a minor surprise in init

1 0

score 0 · Answer 30 · 2025-12-19T09:54:59-05:00

Hello @Ashok Kumar T,

First of all, thank you for bringing .DFI files into the center stage :)

Can you please elaborate on the use case? Have you created the *.DFI files, or are you trying to import someone else's? Is it a one-time import, or are you looking to programmatically create, package, export and import DFI files?