items contained in the VertiGIS package are created on the target ArcGIS Portal.
all intra-package references are recovered after creating the items on the ArcGIS Portal (which leads to new item-ids that need to be respected).
references to items outside of the package need to be resolved through parameter inputs before the deployment takes place.

Install

npm install @vertigis/solution-manager

Features

Building a package

With help of the buildPackage function a package can be generated based on a package description.

The package metadata as well as the items that should be included into the package can be described in a package description json file (e.g. package-definition.json) that has the structure defined in IFileSystemSource.

Sample of using buildPackage function

Install

import { buildPackage } from "@vertigis/solution-manager/export/PackageBuilder";

const sourceDescription = "your-package-definition-dir/package-definition.json";
const sourceDirectory = "your-package-files-dir";
const outputDirectory = "your-output-dir";
const buildPackageResult = await buildPackage({
    sourceDescription,
    sourceDirectory,
    outputDirectory,
});

Sample package description

{
    "description": "Package for  testing the solution-manager-package",
    "documents": [
        {
            "content": "./documents/app/app.json",
            "item": "./documents/app/item.json",
            "resources": {
                "customLibraries/main.js.txt": "./documents/app/main.js.txt",
                "pictures/three-little.png": "./documents/app/res/three-little.png"
            },
            "type": "WebApp",
            "xmlLayouts": { "default": "./documents/app/layout.xml" },
            "customParameters": [
                {
                    "name": "Custom Param",
                    "kind": "CustomText",
                    "valueToReplace": "value-to-replace-1"
                },
                {
                    "name": "Custom Param with Fallback string used as Suggestion",
                    "kind": "CustomText",
                    "valueToReplace": "value-to-replace-2",
                    "fallbackDeployValue": "Fallback"
                },
                {
                    "name": "Custom Param with optional Input and Fallback text used during Deployment",
                    "kind": "CustomText",
                    "valueToReplace": "value-to-replace-3",
                    "optionalInput": true,
                    "fallbackDeployValue": "Fallback"
                },
                {
                    "name": "Custom Param with optional Input and Fallback null used during Deployment",
                    "kind": "CustomText",
                    "valueToReplace": "value-to-replace-4",
                    "optionalInput": true,
                    "fallbackDeployValue": null
                },
                {
                    "name": "Custom Param with Path",
                    "kind": "CustomText",
                    "valueToReplace": "value-to-replace-5",
                    "paths": [
                        "/title"
                    ]
                }
            ]
        }
    ],
    "link": "https://www.vertigis.com/",
    "packageId": "solution-manager-sample-package",
    "packageType": "solution",
    "schema": {
        "classes": [],
        "domains": []
    },
    "version": "0.0.0"
}

Package metadata

As part of the metadata the basic information about the package like id, type (see PackageType), version, description and a link to further information can be specified. See IFileSystemSource for more details.

Package content

The content of the package is also defined in the package description by specifiying one or more documents for the "documents" array. A document can have the settings defined in IFileSystemSourceDocument.

Schema requirements (experimental)

In case the solution packages needs specific feature layers with predefined fields in the feature service / web map at runtime, schema requirements can be defined in the package description as follows:

"schema": {
    "classes": [
    {
        "uniqueId": "My Feature Layer",
        "attributes": [
          "field1",
          "field2"
        ],
        "geometryType": "esriGeometryPolygon"
    }],
    "domains": []
},

These schema requirements are checked during a validation step before the deployment can be performed. In case the chosen data source and web map don't fulfill the specified schema requirements, the deployment can't be performed. See IRequiredSchema for more details.

Deploying a package

With help of the deployPackage function a package can be deployed to an ArcGIS Portal.

Sample of using deployPackage function

import { deployPackage } from "@vertigis/solution-manager/import/PortalPackageDeployer";

const params = {
    portalUrl: "https://your-domain.com/portal",
    username: "your-user",
    password: "your-password",
    solutionPackage:"your-output-dir/solution-manager-sample-package-0.0.0.zip",
    webViewerUrl: "https://your-domain.apps.vertigisstudio.com/web",
    webViewerAccountId: "your-account-id",
    webMapUrl: "https://your-domain.com/portal/sharing/rest/content/items/<id-of-web-map-portal-item>",
    workflowDesignerUrl: "https://your-domain.apps.vertigisstudio.com/workflow/designer/",
    printingParams: {
        url: "https://your-domain.vertigisapps.com/vertigisstudio/printing",
        appId: "your-printing-app-id",
        username: "your-username",
        password: "your-password",
    },
    reportingParams: {
        url: "https://your-domain.vertigisapps.com/vertigisstudio/reporting",
        appId: "your-reporting-app-id",
        username: "your-username",
        password: "your-password",
    },
    appId: "arcgispro",
    buildVersion: "1.0.0",
    customParams: {
        "Custom Param": "my-value-1",
        "Custom Param with Path": "my-value-2",
    },
};

const deployPackageResult = await deployPackage(params);

API Documentation

BuildPackageParams

Input parameters for the buildPackage function.

Properties

Property	Type	Description
`outputDirectory?`	`string`	The output directory (optional). In case it is provided, the package will be exported to this directory. Can either be a relative or absolute path. In case the output directory is not set, no export will happen and the package content will be returned.
`sourceDescription`	`string` \| `IFileSystemSource`	The description of the source files and metadata that should be used for building the package. Can either be: - An object of structure IFileSystemSource or - A path to a JSON file with a JSON of structure IFileSystemSource.
`sourceDirectory`	`string`	The root directory of the source files which should be included into the package (optional). In case the `sourceDescription` contains relative path (starting with "./" or "../") to the files that should be included into the package, the sourceDirectory can be used to tell solution-manager how to resolve these relative paths. If no sourceDirectory is set, the relative paths are resolved from the current working directory where the solution-manager buildPackage function is executed.

BuildPackageResult

The result of building a package. Contains the package and optionally the package file name if an export was performed (depends on whether an output directory was provided).

Properties

Property	Type	Description
`outputFileName?`	`string`	In case an output directory was provided, the name of the exported package file.
`package`	`IFinalPackage`	The final package that was built.

buildPackage()

buildPackage(params): Promise<BuildPackageResult>

Builds a package based on the provided source description and optionally performs an export in case an output directory is provided.

Parameters

Parameter	Type	Description
`params`	`BuildPackageParams`	The input parameters for building the package (@link BuildPackageParams).

Returns

Promise<BuildPackageResult>

Information about the created package.

IFileSystemSource

Re-exports IFileSystemSource

IFileSystemSourceDocument

Re-exports IFileSystemSourceDocument

IFileSystemSource

The description of a source that is used for building a package.

Extends

IPackageCreatorConstructParms

Properties

Property	Type	Description
`customParameters?`	`ICustomParameter`[]	Custom parameters used by all documents.
`description?`	`string`	The description about the package. Will be displayed in the Solution Manager UI.
`documents`	`IFileSystemSourceDocument`[]	List of documents that should be included into the package.
`domain?`	`string`	Used in case of PackageType Domain to specify the domain of the package.
`link?`	`string`	Link to a website that contains additional information about the package.
`packageId`	`string`	The id of the package. Represents the name of the package which is displayed in the Solution Manager UI.
`packageType`	`PackageType`	The type of the package. Available types are defined in the PackageType enum.
`schema`	`IRequiredSchema`	Definition of schema requirements that need to be fulfilled in order to deploy the package.
`version`	`string`	The version of the package (e.g. 1.0.0).

IFileSystemSourceDocument

The description of a file system document that is included into a package.

Properties

Property	Type	Description
`content?`	`string`	The path pointing to a json file containing the portal item's content json. During deployment this information will be used as the content for the created ArcGIS Portal item. In VertiGIS Item Manager the item content is accessible via "Item Content" of the ArcGIS Portal item.
`customParameters?`	`ICustomParameter`[]	Custom parameters used by this document only.
`item`	`string` \| `Document`	Either a portal item's json, or a path pointing to a json file containing the portal item's description json. During deployment this information will be used as the description for the created ArcGIS Portal item. In VertiGIS Item Manager the item description is accessible via "Item JSON" of the ArcGIS Portal item.
`metadata?`	`string`	`Experimental` The path pointing to the metadata file of the item.
`reportOrPrintTemplate?`	`string`	In case of DocumentType ReportTemplate or PrintTemplate, the path pointing to the template file of the item.
`resources?`	`Record`<`string`, `string`>	Resources attached to the item in the form of <key, value> pairs. - Key: name of the resource. - Value: path to the resource file.
`skipUnresolved?`	`boolean`	Specifies whether extracted parameters (e.g. references to other documents) for the document should be skipped unresolved. If skipUnresolved is set to true, the document will be deployed without parameter resolution.
`thumbnail?`	`string`	The path pointing to the thumbnail file of the item.
`title?`	`string`	`Experimental` The title of the item.
`type`	`DocumentType`	The type of the document. Available types are defined in the DocumentType enum.
~~`xmlLayout?`~~	`string`	Deprecated XML Layout string.
`xmlLayouts?`	`Record`<`string`, `string`>	Layouts of a Studio Web App in the form of <key, value> pairs. - Key: app.json item layout ID. - Value: path to the layout file.

IClass<TAttr>

Experimental

Schema definition of a class with id, attributes and geometry type.

Type Parameters

Type Parameter
`TAttr`

Properties

Property	Type	Description
`attributes`	`TAttr`[]	`Experimental` Attributes of the class.
`geometryType`	`string`	`Experimental` Geometry type of the class.
`uniqueId`	`string`	`Experimental` Unique Id of the class.

IRequiredSchema

Experimental

Definition of schema requirements for a package. In case the package needs specific feature layers with predefined fields in the feature service / web map at runtime, schema requirements can be defined. These schema requirements are checked during a validation step before the deployment can be performed. In case the data source and web map chosen for the deployment don't fulfill the specified schema requirements, the deployment can't be performed.

Properties

Property	Type	Description
`classes`	`IRequiredSchemaClass`[]	`Experimental` Definition of a schema containing an array of schema classes that each have an id, attributes and geometry type. The data source selected for the deployment needs to match this schema.
`domains`	`string`[]	`Experimental` Definition of domains that need to exist on the data source.

IRequiredSchemaClass

IRequiredSchemaClass: IClass<string>

Experimental

Definition of a schema class. See IClass for more details. In this case only the field name is required. So use generic IClass<> with type string.

DeployedItem

Information abouth the item that was deployed.

Properties

Property	Type	Description
`id`	`string`	Id of the item.
`targetId`	`string`	Id of the portal item that was created on the portal.
`title`	`string`	Title of the item.
`type`	`string`	Type of the item.

DeployedPackage

Information about a deployed package.

Properties

Property	Type	Description
`items`	`DeployedItem`[]	Items that are created on the portal during the deployment.
`packageId`	`string`	Id of the package.
`packageType`	`string`	Type of the package.
`portalItemId`	`string`	Id of the portal item that was created for the package. This portal item contains metadata about the deployment.
`version`	`string`	Version of the package.

DeployPackageParams

Input parameters for the deployPackage function. Note: Either username/password or refreshToken is needed to get access to the ArcGIS Portal and perform the deployment.

Properties

Property	Type	Description
`customParams?`	`Record`<`string`, `string`>	Values for custom parameters that are resolved during the deployment process. The key is the name of the custom parameter and the value is the value that should be used for the deployment.
`datasourceId?`	`string`	Id of the datasource that should be used with the deployed application. Note: This parameter is mandatory if the deployed package has schema requirements which need to be checked.
`domainPackage?`	`string`	Path to the domain package that should be deployed.
`password?`	`string`	Password of the ArcGIS Portal user that is used to perform the deployment.
`portalRefreshToken?`	`string`	Refresh token for the ArcGIS Portal that is used to perform the deployment.
`portalUrl`	`string`	URL of the ArcGIS Portal to which the package will be deployed.
`printingParams?`	`PrintingReportingParams`	Parameters to get access to the printing/reporting server. See PrintingReportingParams for more details.
`reportingParams?`	`PrintingReportingParams`	Parameters to get access to the printing/reporting server. See PrintingReportingParams for more details.
`solutionPackage`	`string`	Path to the solution package that should be deployed.
`tag`	`string`	Tag that is set for all deployed items on the ArcGIS Portal.
`username?`	`string`	Username of the ArcGIS Portal user that is used to perform the deployment.
`webMapUrl?`	`string`	Url of the Web Map that should be used with the deployed application. For example: "https://your-domain.com/portal/sharing/rest/content/items/".
`webViewerAccountId?`	`string`	Studio Web Account ID.
`webViewerUrl?`	`string`	Studio Web Viewer URL. For example: "https://your-domain.apps.vertigisstudio.com/web".
`workflowDesignerUrl?`	`string`	Studio Workflow Designer URL. For example: "https://your-domain.apps.vertigisstudio.com/workflow/designer/".

DeployPackageResult

The result of deploying a package.

Properties

Property	Type	Description
`name`	`string`	Name of the deployment.
`packages?`	`DeployedPackage`[]	The deployed packages.
`portalItemId?`	`string`	Id of the Portal Item that contains metadata about the deployment.

PrintingReportingParams

Parameters to get access to the printing/reporting server. Either refreshToken or username/password are needed to get access to printing/reporting server.

Note: Deployment with username/password only works if app:EnableStrictAppIdCheck is TEMPORARILY disabled in C:\Program Files\VertiGIS\VertiGIS Studio [Printing\Reporting]\Deployment\web.config alternatively the refreshToken has to be used.

Properties

Property	Type	Description
`appId`	`string`	AppId to get access to the printing/reporting server. Can be found in the VertiGIS Studio Printing/Reporting authentication file that was created during installation of VertiGIS Studio Printing/Reporting.
`password?`	`string`	Password of the ArcGIS Portal user that is used to get access to the printing/reporting server.
`refreshToken?`	`string`	Refresh token for the printing/reporting server that is used to get access to the printing/reporting server.
`url`	`string`	Printing/Reporting Server URL. For example: "https://your-domain.vertigisapps.com/vertigisstudio/reporting".
`username?`	`string`	Username of the ArcGIS Portal user that is used to get access to the printing/reporting server.

deployPackage()

deployPackage(params): Promise<DeployPackageResult>

Deploys a package on the provided ArcGIS Portal.

Parameters

Parameter	Type	Description
`params`	`DeployPackageParams`	The input parameters for deploying the package (@link DeployPackageParams).

Returns

Promise<DeployPackageResult>

Information about the deployed package.

CustomParameterKind

Supported custom parameter kinds. Values should match the custom kinds in enum ParameterKind.

Enumeration Members

Enumeration Member	Value	Description
`CustomText`	`"CustomText"`	Custom text to replace.
`CustomUrl`	`"CustomUrl"`	Custom url to replace.

DocumentType

Supported document types.

Enumeration Members

Enumeration Member	Value	Description
`ActivityPack`	`"ActivityPack"`	VertiGIS Studio Workflow Activity Pack.
`FeatureServicePointer`	`"FeatureServicePointer"`	Esri Feature Service Pointer.
`FileGeodatabase`	`"FileGeodatabase"`	Esri File Geodatabase.
`HostedFeatureLayer`	`"HostedFeatureLayer"`	Esri Hosted Featuer Layer.
`MobileApp`	`"MobileApp"`	VertiGIS Studio Mobile App.
`Notebook`	`"Notebook"`	Esri Jupyter Notebook.
`PrintTemplate`	`"PrintTemplate"`	VertiGIS Studio Print Template.
`ReportTemplate`	`"ReportTemplate"`	VertiGIS Studio Report Template.
`Shapefile`	`"Shapefile"`	Esri Shapefile.
`WebApp`	`"WebApp"`	VertiGIS Studio Web App.
`WebMap`	`"WebMap"`	Esri Web Map.
`WebMappingApplication`	`"WebMappingApplication"`	Esri Web Mapping Application.
`Workflow`	`"Workflow"`	VertiGIS Studio Workflow.

PackageType

Supported package types.

Enumeration Members

Enumeration Member	Value	Description
`Domain`	`"domain"`	A domain package. Contains items that configure how solutions can interact with a specific domain data model.
`Solution`	`"solution"`	A solution package. Contains items that build the basis for solution functionality.

ParameterUsage

Supported parameter usages.

Enumeration Members

Enumeration Member	Value	Description
`Interactive`	`"interactive"`	Interactive parameter. User can see and (usually) change it.
`System`	`"system"`	Hidden / non-interactive parameter.

ICustomParameter

Custom parameter definition.

Properties

Property	Type	Description
`fallbackDeployValue?`	`string`	The fallback deploy value is used in the following cases. - For a parameter with optional input: In case no value is provided for the parameter, the fallback deploy value is used during the deployment. - For a parameter with required input: - In Solution Manager UI the fallback deploy value is used as suggestion on the parameter overview page. - When calling the deployPackage function the fallback deploy value is used during the deployment in case no value for the parameter was provided.
`kind`	`CustomParameterKind`	Custom parameter's kind.
`name`	`string`	Name of the custom parameter. Displayed in the Solution Manager UI on the parameters page.
`optionalInput?`	`boolean`	Whether the custom parameter input is optional. If it is set to true, the user doesn't need to provide a value for this parameter before the deployment. In case the user chooses to not provide a value for an "optionalInput" parameter, the valueToReplace is replaced during the deployment with the fallbackDeployValue (if provided) or an empty string. If nothing specified for optionalInput, the custom parameter per default requires a non-empty input.
`paths?`	`string`[]	JSON/XML/... Paths pointing to locations that shall be filled with value. If not specified, valueToReplace will be applied to the whole content.
`usage?`	`ParameterUsage`	Parameter usage. Default: Interactive.
`valueToReplace`	`string`	Value to replace.

IFinalPackage

The structure of a package containing a manifest with metadata and the data.

Properties

Property	Type	Description
`data`	`any`	The data of the package.
`manifest`	`IManifest`	The manifest containing the metadata about the package.

Keywords

FAQs

What is @vertigis/solution-manager?

Is @vertigis/solution-manager well maintained?

Package last updated on 01 Apr 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@vertigis/solution-manager