Last updated: 2024-11-14

ShareAspace development tool

Introduction

The ShareAspace development tool serves two main purposes.

To run an "offline" version of ShareAspace where the tool can load in ShareAspace data store backups and allow for script execution against said data stores.
To provide ShareAspace software development kits and help developers setting up project stubs for different types of ShareAspace based development projects.
- e.g. see offline-export.

Installation

Server environment

Pre-requisites

ShareAspace Nova Host Service (see pre-requisites).
ShareAspace development tool.

Installation

Unpack the ShareAspace development tool sas-devtool_<version>.zip, (e.g sas-devtool_1.7.18.123.zip) at a place where the sas-devtool.exe can be executed by the user account that will run the operations against the ShareAspace store.

Setup a system PATH variable for the folder where the tool was extracted (e.g C:\Program Files\Eurostep\ShareAspace\sas-devtool).

Development environment

Pre-requisites

ShareAspace development tool
(Optional/recommended) Microsoft Visual Studio Code.
- Recommended Visual Studio Code plugins (when opening the ShareAspace dev tool project template - Visual Studio will automatically suggest these extensions)
  - editorconfig.editorconfig
  - denoland.vscode-deno
(Optional/recommended) Deno.
(Optional) ShareAspace Nova Host Service (see pre-requisites).

Installation

Setup a system PATH variable for the folder where the tool was extracted (e.g C:\Program Files\Eurostep\ShareAspace\sas-devtool).

Command line interface

sas-devtool

The ShareAspace development command line interface is self describing. Running the root application sas-devtool the following help information is displayed. From here it is possible to get further help by navigating the command line interface menu system.

PS > sas-devtool
Usage: sas-devtool <command> [options]
Options:
  -v, --version                  Output the version number
  -h, --help                     Output usage information
Commands:
  generate [options] <input...>  Generates TypeScript types from a ShareAspace template
  build [options] <input...>     Bundles for production
  sas <command>                  Execute commands against ShareAspace.
  init <input...>                Initialize a new ShareAspace project from template.
  help <command>                 Displays help information for a command

Run 'sas-devtool help <command>' for more information on specific commands

Usage

sas-devtool <command> [options]

Options

Option	Description
`-v, --version`	Output the version number.
`-h, --help`	Output usage information.

Commands

Command	Description
`generate [options] <input...>`	Generates TypeScript types from a ShareAspace template.
`build [options] <input...>`	Bundles for production.
`sas <command>`	Execute commands against ShareAspace.
`init <input...>`	Initialize a new ShareAspace project from template.
`help <command>`	Displays help information for a command.

Note

Run sas-devtool help <command> for more information on specific commands.

generate

Generates TypeScript types from a ShareAspace space template.

Usage

sas-devtool generate [options] <template> <output path>

Options

Option	Description
`-h, --help`	Display help for command.
`--log-level <level>`	Sets the log level. "error", "warn", "info", "debug" or "trace". Default is "info".
`--ignore-errors`	Tell the generator to ignore the errors found and try to generate output anyway.
`--no-emit`	Run all the validation logic but don't emit any output.

Inputs

Input	Description
`<template>`	The path to the ShareAspace space template file.
`<output path>`	The path to were the TypeScript files should be generated.

build

Bundles for production.

Usage

sas-devtool build [options]

Options

Option	Description
`--dist-dir <dir>`	Output directory to write to when unspecified by targets.
`-h, --help`	Display help for command.
`--log-level <level>`	Sets the log level. "error", "warn", "info", "debug" or "trace". Default is "info".

sas

A group of commands executed against the ShareAspace Host.

Usage

sas-devtool sas <command>

Commands

Command	Description
`run [options] <input...>`	Run a JavaScript file in the ShareAspace script runtime.
`config <command>`	Global configuration commands for sas-devtool.
`list <command>`	List different types of ShareAspace resources.
`create <command>`	Create commands for ShareAspace resources.
`add <command>`	Add an existing resource to ShareAspace.
`restore [options] <input...>`	Restore a ShareAspace system from a collection and space checkpoint.
`help <command>`	Displays help information for a command.

sas run

Run a JavaScript file in the ShareAspace script runtime.

Usage

sas-devtool sas run [options] <space id> <script>

Options

Option	Description
`-h, --help`	Display help for command.
`--log-level <level>`	Sets the log level. "error", "warn", "info", "debug" or "trace". Default is "info".
`--launch-debugger`	Launch the .NET debugger in the ShareAspace host just before script execution.
`--system-path`	The path to the ShareAspace system store directory (override global config).
`--host-path`	The path to the ShareAspace 'Eurostep.SAS.ServiceHost.exe' (override global config).

Inputs

Input	Description
`<space id>`	The id of the space the script will be executed in.
`<script>`	The path to the script file that should be executed.

sas config

To make it easier to use sas-devtool it is possible to set some global configuration options that will be used for all commands.

Usage

sas-devtool sas config <command>

Commands

Command	Description
`set <key> <value>`	Set the global config.
`get <key>`	Get the global config.

sas config set

Set the global config <key> to <value>.

Usage

sas-devtool sas config set <key> <value>

Keys:

Key	Description
`system-path`	The path to the ShareAspace system store directory.
`host-path`	The path to the ShareAspace 'Eurostep.SAS.ServiceHost.exe'.

sas config get

Get the global config <key>.

Usage

sas-devtool sas config get <key>

Keys:

Key	Description
`system-path`	The path to the ShareAspace system store directory.
`host-path`	The path to the ShareAspace 'Eurostep.SAS.ServiceHost.exe'.

sas list

List different type of ShareAspace resources.

Usage

sas-devtool sas list <command>

Commands

Command	Description
`spaces [options]`	List all ShareAspace spaces available.

sas list spaces

List all ShareAspace spaces available.

Usage

sas-devtool sas list spaces

sas create

Create commands for ShareAspace.

Usage

sas-devtool sas create <command>

Commands

Command	Description
`system [options] <input...>`	Creates a new ShareAspace system store.

sas create system

Create a new ShareAspace system store. If the create is successful the system store path is stored in the global configuration and is used for other commands.

Usage

sas-devtool sas create system <input...>

Options

Option	Description
`-h, --help`	Display help for command.
`--log-level <level>`	Sets the log level. "error", "warn", "info", "debug" or "trace". Default is "info".
`--host-path`	The path to the ShareAspace 'Eurostep.SAS.ServiceHost.exe' (override global config).

Inputs

Input	Description
`<system path>`	The path to were the ShareAspace system store should be located (the directory must be empty).
`<base storage path>`	The base directory were all other storage should be located (if you plan on adding existing storages they should be located in this directory).
`<base file vault path>`	The base directory were all file vault sub directories will be located.

sas add

Adds something to an existing ShareAspace system.

Usage

sas-devtool sas add <command>

Commands

Command	Description
`collection [options] <input...>`	Adds a ShareAspace collection storage to a ShareAspace system storage.
`space [options] <input...>`	Adds a ShareAspace space storage to a ShareAspace system store.

sas add collection

Adds a ShareAspace collection storage to a ShareAspace system storage.

Usage

sas-devtool sas add collection <input...>

Options

Option	Description
`-h, --help`	Display help for command.
`--log-level <level>`	Sets the log level. "error", "warn", "info", "debug" or "trace". Default is "info".
`--system-path`	The path to the ShareAspace system store directory (override global config).
`--host-path`	The path to the ShareAspace 'Eurostep.SAS.ServiceHost.exe' (override global config).

Inputs

Input	Description
`<storage path>`	The path to the ShareAspace collection storage directory.
`<file valut path>`	The path to the ShareAspace collection file value directory.

sas add space

Adds a ShareAspace space storage to a ShareAspace system store.

Usage

sas-devtool sas add space <input...>

Options

Option	Description
`-h, --help`	Display help for command.
`--log-level <level>`	Sets the log level. "error", "warn", "info", "debug" or "trace". Default is "info".
`--system-path`	The path to the ShareAspace system store directory (override global config).
`--host-path`	The path to the ShareAspace 'Eurostep.SAS.ServiceHost.exe' (override global config).

Inputs

Input	Description
`<space id>`	The id of the space to be added.
`<storage path>`	The path to the ShareAspace collection storage directory.
`<file valut path>`	The path to the ShareAspace collection file value directory.

sas restore

Restore a ShareAspace system from a collection and space checkpoint.

Usage

sas-devtool sas restore <input...>

Options

Option	Description
`-h, --help`	Display help for command.
`--log-level <level>`	Sets the log level. "error", "warn", "info", "debug" or "trace". Default is "info".
`--host-path`	The path to the ShareAspace 'Eurostep.SAS.ServiceHost.exe' (override global config).

Inputs

Input	Description
`<base storage path>`	The base directory were all other storage should be located (if you plan on adding existing storages they should be located in this directory).
`<base file vault path>`	The base directory were all file vault sub directories will be located.
`<checkpoint id>`	The id of the checkpoint to restore.
`<checkpoint zip file>`	The ZIP file containing the collection and space to restore.

init

Initialize a ShareAspace project from the template <template> into the empty directory in <path>.

Usage

sas-devtool init <template> <path>

Inputs

Input	Description
`<template>`	The name of the project template.
`<path>`	The path were the project should be initialized (it must be an empty directory).

Templates

Template	Description
`offline-export`	TypeScript project template to run in the ShareAspace offline script mode, e.g. for exporting data or doing analysis.

ShareAspace Core API - 0.1.0

get

Get a SoftType instance from ShareAspace.

function get<T extends SoftTypeBase>(oid: ObjectId): T | undefined

Parameter	Type	Description
`oid`	ObjectId	The ObjectId of the SoftType that is fetched from ShareAspace.

Returns SoftTypeBase.

getAll

Get all SoftType instances for a given SoftType id.

function getAll<T extends SoftTypeBase>(softTypeId: string): T[]

Parameter	Type	Description
`softTypeId`	`string`	The id of the SoftType for which all instances should be requested.

Returns SoftTypeBase[].

getDefaultPresentation

Get the default presentation for the give SoftType instance.

function getDefaultPresentation(data: SoftTypeBase, languageCode?: string): string | undefined

Parameter	Type	Description
`data`	SoftTypeBase	The SoftType instance to get default presentation for.
`languageCode`	`string`	Optional language code if not given 'en' is used.

Returns SoftTypeBase[].

ObjectId

ShareAspace database id.

type ObjectId = string

SoftTypeBase

Base type for all generated SoftType type definitions.

type SoftTypeBase = {
  $oid: ObjectId
  $softType: string
}

Property	Type	Description
`$oid`	ObjectId	Database id of the SoftType instance.
`$softType`	`string`	Id of the SOftType definition that the SoftType instance is tagged as.

QueryParams

Query execution setting parameters.

type type QueryParams = {
  queryId: string,
  arguments?: Record<string, string | number | boolean | Date>,
  latestVersion?: boolean,
  orderTerm?: string,
  orderDescending?: boolean,
  page?: number
  pageSize?: number
}

Property	Type	Description
`queryId`	`string`	Id of query to execute.
`arguments`	`Record<string, string \| number \| boolean \| Date>`	(Optional) Query input parameters for queries that has a query expression with blank value fields.
`latestVersion`	`boolean`	(Optional) If set to `true`, when querying for MVD-objects, only the "latest version" MVD-objects will be returned. By default the "latest version" is the last version in the version chain - however, this can be overridden by the latest version filter.
`orderTerm`	`string`	(Optional) Index term id that the result should be ordered by.
`page`	`number`	(Optional) Result page to return, defaults to page 0.
`pageSize`	`number`	(Optional) The size of the returned pages, defaults to 10.

QueryBase

Base type for all generated Query return type definitions. Each QueryBase represents an indexed SoftType instance.

type QueryBase = {
  oid: ObjectId
}

Property	Type	Description
`oid`	ObjectId	Database id of indexed SoftType instance.

query

Function for executing a query against a database.

function query<T extends QueryBase>(arg: QueryParams): T[]

Parameter	Type	Description
`arg`	QueryParams	Query execution setting parameters.

Returns QueryBase[].

SoftTypeDefinition

Not documented - see the type script definition for more details. types/sas/core@0.1.0/mod.ts

getSoftTypeDefinition

Gets a SoftType definition configuration from the space configuration.

function getSoftTypeDefinition(softTypeId: string): SoftTypeDefinition

Property	Type	Description
`softTypeId`	`string`	Id of the SoftType definition to get configuration settings for.

Returns SoftTypeDefinition[].

ShareAspace IO API - 0.1.0

import { createCSVWriter, CSVWriterOptions, CSVWriter } from "sas.io@0.1.0"

Export	Kind
CSVWriter	`type`
CSVWriterOptions	`type`
createCSVWriter	`function`

CSVWriter

Writes rows to a CSV file and manages the closing of the writer stream.

type CSVWriter = {
  write: (...args: any[]) => void
  close: () => void
}

Method	Input	Returns	Description
`write`	`any[]`		Writes a new row to the `CSV` file, the first input value will be put in the first column, the second input value in the second column and so on.
`close`			Closes the `CSV` write stream.

CSVWriterOptions

Settings used when requesting a CSVWriter.

type CSVWriterOptions = {
  file: string
  headers: string[]
  delimiter: string
  overwrite: boolean
}

Property	Description
`file`	The full name of the output `CSV` file. If only a name is given the file will be output in the current working directory. If a file already exist `output.csv` a new file will be created called `output (1).csv`. If `output (1).csv` exist, `output (2).csv` will be created and so on.
`headers`	A string array of the `CSV` column headers.
`delimiter`	The delimiter character to be used for the CSV file. defaults to `,`.
`owerwrite`	If set to `true` the report will overwrite any existing file found at `file`.

createCSVWriter

Function for requesting a new instance of a CSVWriter.

function createCSVWriter(options: CSVWriterOptions): CSVWriter

Parameter	Type	Description
`options`	CSVWriterOptions	Settings for the CSVWriter.

Returns CSVWriter.

Table of Contents

ShareAspace development tool

Introduction

Installation

Server environment

Pre-requisites

Installation

Development environment

Pre-requisites

Installation

Command line interface

sas-devtool

Usage

Options

Commands

Note

generate

Usage

Options

Inputs

build

Usage

Options

sas

Usage

Commands

sas run

Usage

Options

Inputs

sas config

Usage

Commands

sas config set

Usage

Keys:

sas config get

Usage

Keys:

sas list

Usage

Commands

sas list spaces

Usage

sas create

Usage

Commands

sas create system

Usage

Options

Inputs

sas add

Usage

Commands

sas add collection

Usage

Options

Inputs

sas add space

Usage

Options

Inputs

sas restore

Usage

Options

Inputs

init

Usage

Inputs

Templates

ShareAspace Core API - 0.1.0

get

getAll

getDefaultPresentation

ObjectId

SoftTypeBase

QueryParams

QueryBase

query

SoftTypeDefinition