How to Create DCF and SPK Files for Deploying Custom TERR/R Packages to Spotfire Statistics Services (TERR Service)

Keywords:
TERR Service, SpotfireSPK, SPK, DCF, custom package, custom application, buildServerSPK, package deployment, Spotfire Server, TERR package management

Purpose

This article describes how to create a DCF file and generate an SPK package for deploying custom TERR/R packages to Spotfire Statistics Services (TERR Service). It also covers common errors related to package dependencies and TERR compatibility.

Environment

• Spotfire Enterprise Runtime for R (TERR) 6.1.8
• Microsoft Windows 64-bit
• SpotfireSPK package
• Custom TERR/R package(s) to be deployed to TERR Service

Prerequisites

• The package to be deployed must be installed in a TERR-accessible library.
• All package dependencies must be available in the same library path.
• The SpotfireSPK package must be installed and loaded.

library(SpotfireSPK)

To view SPK creation documentation:

help(topic = "buildServerSPK", package = "SpotfireSPK")

Step 1: Create a Custom Library Location

custom_lib <- temp="TEMP" terr_spk_lib_custom="terr_spk_lib_custom" showwarnings="FALSE," recursive="TRUE">

Verify the configured library paths:

.libPaths()

Step 2: Install the Custom Package

Install the custom package source archive into the custom library location.

install.packages(
  "C:/TEMP/custom-package.tar.gz",
  repos = NULL,
  type = "source",
  lib = custom_lib
)

Validate the installation:

installed.packages(
  lib.loc = custom_lib
)[, c("Package", "Version")]

find.package("custom.package")

Step 3: Create the DCF File

Create a package list that will be used by SpotfireSPK during package generation.

packages_to_bundle <- collapse="," temp="TEMP">

Validate the DCF contents:

readLines("C:/TEMP/TERRPackages_custom.dcf")

Expected output:

Packages: custom.package

Step 4: Build the SPK Package

buildServerSPK(
  listFile = "C:/TEMP/TERRPackages_custom.dcf",
  spkFile = "C:/TEMP/terr_packages_custom.spk"
)

If successful, the following file will be created:

C:/TEMP/terr_packages_custom.spk

Common Errors and Resolutions

Package Not Installed

Warning:
no package 'custom.package' was found

Error:
package 'custom.package' is not installed

Cause: The package is not available in any library path visible to TERR.

Resolution:

• Install the package into the custom library.
• Ensure the library path is included in .libPaths().
• Verify the package using find.package().

Missing Dependency

Error:
package '<dependency>' is not installed

Cause: One or more required packages listed in Imports, Depends, or recursive dependency chains are missing.

Resolution:

• Install all required dependencies.
• Validate that each dependency can be located by TERR.
• Retry SPK generation.

To review package dependencies:

packageDescription("custom.package")$Imports

packageDescription("custom.package")$Depends

tools::package_dependencies(
  "custom.package",
  recursive = TRUE
)

R Version Compatibility Warning

package requires R version X.X.X

TERR supports R version Y.Y.Y

Cause: The package requires a newer R version than the version supported by TERR.

Resolution:

• Review the package DESCRIPTION file.
• Confirm package compatibility with the TERR-supported R version.
• Rebuild the package if necessary.
• Upgrade TERR if supported and appropriate.

Recommended Validation Steps Before SPK Creation

1. Create a dedicated TERR library.
2. Install the custom package.
3. Install all dependencies.
4. Verify package visibility using find.package().
5. Review package dependencies.
6. Validate TERR/R version compatibility.
7. Create the DCF file.
8. Run buildServerSPK().
9. Confirm successful SPK creation.
10. Deploy the SPK through Spotfire Server deployment mechanisms.

Key Findings

• buildServerSPK() validates package dependencies before creating the SPK.
• All packages referenced in Depends and Imports must be installed and available.
• Custom package libraries must be included in .libPaths().
• R version mismatches may prevent successful deployment or runtime execution.
• Dependency validation failures stop SPK generation until all required packages are available.

Conclusion

Creating an SPK package for TERR Service requires more than simply listing packages in a DCF file. All dependencies must be installed and accessible, and package requirements must be compatible with the TERR runtime version. Following the validation steps outlined above can significantly reduce SPK creation and deployment issues.