Introduction

Artifact Management on SAP BTP facilitates the generation of project metadata comprising of multiple modules of different technologies,
bundles the module into one single deployment artifact and supports one click deploy to Cloud Foundry

Key Capabilities

* Access to project properties
* Access to VSCode workspace
* Provide list of modules and items of each module
* Watchers to notify of changes to project
* Support of tags and filter
* Capability to Test run
* Capability to generate
MTA yaml and
MTAR
* Deployment of MTAR to Cloud Foundry
* Plugins for SAP technologies such as
MDK,
FioriElement,
CAP,
XSUAA

---

$3

* Node.JS 12 or higher
* CAP Development Kit (npm install -g @sap/cds-dk)

$3

* MTAR builder (npm install -g mbt)
* Install [lerna] for mono-repo building (npm install -g lerna)
* Install MDK-Tools, npm install @sap/mdk-tools -g
* Cloud Foundary CLI, Install cf-cli and run command cf install-plugin multiapps.

---

$3

``
npm i -g @sap/artifact-management
`
There are two main sets of classes provided by the library.
- ProjectApi, ProjectImpl : These are the interface and implmentation classes respectively for project level usages.
- WorkspaceApi, WorkspaceImpl : These are the interface and implmentation classes respectively for Workspace level usages.

You can import the module in your code as follows:
import { ProjectImpl } from '@sap/artifact-management';

To initialise Project API, instance of ProjectImpl has to be created which takes absolute path of a project.
`
import { ProjectImpl } from '@sap/artifact-management';
const path = '';

/**
* readModuleAsProject Default value is false.
* If the boolean is false, then only lcap/cap projects are read.
* If true then any project can also be read.
*/
const readModuleAsProject = false

const project = new ProjectImpl(path ,readModuleAsProject);
`

To initialise Workspace API, instance of WorkspaceImpl has to be created.
`
import { WorkspaceImpl } from '@sap/artifact-management';

const path = '';
const workspace = new WorkspaceImpl(path);
`
or
`
import * as vscode from 'vscode';
import { WorkspaceImpl } from '@sap/artifact-management';

const workspace = new WorkspaceImpl(vscode);
`

The library also provides the object CommandExecutor to help create customized CLI tools. On BAS, for example, use the basctl tool to call Project API which resides on an BAS extenison.

---


APIs & Examples

Access to VSCode workspace

$3

###### Description
Get all the projects in the workspace. Get the project based on tag if provided and Return type is array of ProjectAPIs / Returns ProjectAPI based on the tag.
###### Method
getProjects(tag?: Tag) : Promise

###### Parameters
- tag: (Optional) Tag value which can be used to filter projects.
###### returns
- array of ProjectApi instance or undefined

###### Example
`
import {Tag} from @sap/artifact-management' //Optional
const ws = new WorkspaceImpl(workspacePath);
const projects = await ws.getProjects();
`

$3


###### Description
Get the project with specific path.Return the ProjectAPI object based on the path.
###### Method
getProject(path: string) : Promise

###### Parameters
- path: the path of a project. It could be absolute or relative.
###### returns
- ProjectApi instance or undefined

###### Example
`
const ws = new WorkspaceImpl(workspacePath);
const path = '/Users/me/projects/lcap-project';
const project = await ws.getProject(path);
`

$3


###### Description
Get all project Uris in the workspace.
###### Method
getProjectUris(): Promise

###### returns
- array of string or undefined

###### Example
`
const ws = new WorkspaceImpl(workspacePath);
const projectUris = await ws.getProjectUris();
`




$3


###### Description
it detects File addition or deletions in workspace and triggers the updated event
###### Method
startWatch() : void

###### returns
- void

###### Example
`
const ws = new WorkspaceImpl(workspacePath);
await ws.startWatch();
`




$3


###### Description
it stops the watch event
###### Method
stopWatch() : void

###### returns
- void

###### Example
`
const ws = new WorkspaceImpl(workspacePath);
await ws.stopWatch();
`

$3


###### Description
it captures the add/remove events for the folders in the Workspace
###### Method
onWorkspaceChanged(handler: (event: string, folders: string[]) => void) : void

###### Parameters
- a function which takes a string event ("add" | "remove") and array of string as arguments

###### returns
- void

###### Example
`
import * as vscode from 'vscode';
const ws = new WorkspaceImpl(vscode);
ws.onWorkspaceChanged((event: string, folders: WorkspaceFolder[]) => {
// add implementation
});
`


$3


###### Description
it returns an IPluginManager instance which can be used to register the custom plugin.
###### Method
getPluginManager() : IPluginManager

###### returns
- an IPluginManager instance

###### Example
`
import * as vscode from 'vscode';

const ws = new WorkspaceImpl(vscode);
const pluginManager = ws.getPluginManager();
pluginManager.register(customPlugin);
`
---

Access to project properties

$3

###### Description
Read the entire project and return the information about project, its CAP modules and their items.
###### Method
read(logger? : IChildLogger, tag? : Tag): Promise;

###### Parameters
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of Project API.
- tag: (Optional) Tag value which can be used to filter projects.
###### returns
- Project instance or undefined

###### Example
`
import {Tag} from @sap/artifact-management' //Optional
const api = new ProjectImpl(projectPath);
const project = await api.read();
`
###### CLI

`
dev-project show
`

###### Sample Output
`
{
"type": "com.sap.cap",
"path": "",
"prefix": "DemoProject",
"cloudService": "com.DemoProject",
"name": "DemoProject",
"tags": [
"project",
"cap"
],
"modules": [
{
"type": "com.sap.security.XsSecurity",
"name": "_To_Be_Generated_",
"path": "",
"items": []
}
]
}
`

$3


###### Description
Reads only Project level information without reading its modules and items. If there are MTA extension files in the project, the file list of MTA extension will be added to the info property in the returned PorjectData object.
###### Method
getProjectInfo(logger? : IChildLogger): Promise;
###### Parameters
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of Project API.
###### returns
- ProjectData or undefined
###### Example
`
const api = new ProjectImpl(projectPath);
const project = await api.getProjectInfo();
`
###### CLI
`
dev-project get-project-info
`
###### Sample Output
`
{
"type": "com.sap.cap",
"path": "",
"prefix": "DemoProject",
"cloudService": "com.DemoProject",
"name": "DemoProject",
"tags": [
"project",
"cap"
],
"info": {
"mtaExtensions": [
"extension1.mtaext",
"extension2.mtaext"
]
}
}
`
---

Provide list of modules and items of each module

$3

###### Description
Reads only module level information for all the modules in the project without reading their items.
###### Method
getModules(logger? : IChildLogger): Promise;
###### Parameters
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- Array of ModuleData or undefined
###### Example
`
const api = new ProjectImpl(projectPath);
const project = await api.getModules();
`
###### CLI
`
dev-project get-modules-info
`
###### Sample Output
`
[
{
"type": "com.sap.security.XsSecurity",
"name": "_To_Be_Generated_",
"path": ""
}
]
`

$3

###### Description
Read the entire project and return the information about all the items/entities in the project.
###### Method
readItems(filter? : ItemFilter, logger? : IChildLogger) : Promise;
###### Parameters
- filter: (Optional) ItemFilter which can be used to filter items in the project.
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- An array of Item
###### Example
`
import {ItemFilter} from @sap/artifact-management' //Optional
const api = new ProjectImpl(projectPath);
const project = await api.readItems();
`

###### CLI

Read all items

`
dev-project list-items
`
###### Sample Output

`
[
{
"external": false,
"name": "fioriApp",
"namespace": "sap.ui.demoproject",
"path": "db/schema.cds",
"ref": "sap.ui.demoproject.fioriApp",
"tags": [
"item",
"cap"
],
"type": "com.sap.cds/Entity"
},
...
...
...
]
`


$3


###### Description
Read the entire project and return the information about all the detail items/entities in the project.
###### Method
readDetailItems(filter? : ItemFilter, logger? : IChildLogger) : Promise;
###### Parameters
- filter: (Optional) ItemFilter which can be used to filter items in the project.
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- An array of Item
###### Example
`
import {ItemFilter} from @sap/artifact-management' //Optional
const api = new ProjectImpl(projectPath);
const project = await api.readDetailItems();
`

###### CLI

Read all items with detail information

`
dev-project list-detail-items
`
###### Sample Output

`
[
{
"external": false,
"name": "fioriApp",
"namespace": "sap.ui.demoproject",
"path": "db/schema.cds",
"ref": "sap.ui.demoproject.fioriApp",
"tags": [
"item",
"cap"
],
"type": "com.sap.cds/Entity",
"info": {
"attributes": {
"ID": {
"@Core.Computed": true,
"key": true,
"type": "cds.UUID"
},
"name": {
"type": "cds.String",
"length": 100
}
}
}
},
...
...
...
]
`
---




Watchers to notify of changes to project


###### Description
Read and watch the items/entities in the project. Any changes in the items addition, deletion or updation which match the watch criteria will be notified by the event updated which is listened by ItemWatcherApi.
###### Method
watchItems(filter? : ItemFilter, logger? : IChildLogger) : Promise;
###### Parameters
- filter: (Optional) ItemFilter which can be used to filter items in the project.
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- ItemWatcherApi. This can be used to read the updated items.

###### Example
`
import {ItemFilter} from @sap/artifact-management' //Optional
const project = new ProjectImpl(projectPath);
const itemWatcher = await project.watchItems();
const items = await itemWatcher.readItems();
itemWatcher.on('updated', () => {
console.log('Items updated');
});
`

###### CLI

Read all items

`
dev-project watch-items
`

---




Support of Filters


###### Description
Items can be filtered on basis of type, tag and ref
The filter can be passed in readItems and watchItems APIs as an argument which will return items based on the filter. Check readItems and watchItems APIs for further information

###### Example
`
import {ItemFilter} from @sap/artifact-management'

// Filter by type
const filter: ItemFilter = {types: ["com.sap.cds/Entity"]};

// Filter by tags
const filter: ItemFilter = {​​​tags: {​​​values: ["db", "srv"]}​​​}​​​;

// Filter by refs
const filter: ItemFilter= {refs: [""]​​​}​​​;


const api = new ProjectImpl(projectPath);
const entities = await api.readItems(filter);
`

---

Capability to Test run


###### Method
run(option?: string[] | undefined, logger? : IChildLogger ) : Promise
###### Description
It starts the CDS server and watches for any modifications in the files, if any changes detected it automatically restarts to serve the new content
###### Parameters
- options: (Optional) run options. Comma separated list of options and their values. e.g. ['port', '8008', 'open']. Currently only supports port number and open option.
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- Promise
###### Example
`
const api = new ProjectImpl(projectPath);
await api.run();
`
###### CLI
`
dev-project run port 9039 open
`

---

Capability to generate MTA yaml and MTAR

###### Method
build(options? : MtaGeneratorSettings, logger? : IChildLogger) : Promise;
###### Description
Generate manifest for the project and all the modules and create a mta.yaml and .mtar file.
###### Parameters
- options: (Optional) MtaGeneratorSettings build options.
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- Promise
###### Example
`
const api = new ProjectImpl(projectPath);
await api.build();
`
###### CLI
`
dev-project build
`
###### Sample Output
`
_schema-version: '3.1'
ID: DemoProject
version: 1.0.0
description: A simple CAP project.
parameters:
enable-parallel-deployments: true
build-parameters:
before-all:
- builder: custom
commands:
- bash -c "cds compile srv --to xsuaa > xs-security.json"
- builder: custom
commands:
- npm install --production
- >-
bash -c "cds -v 2>/dev/null >/dev/null || npm install --no-save
@sap/cds-dk"
- npx cds build --production
modules:
- name: DemoProject-db-deployer
type: hdb
path: gen/db
parameters:
buildpack: nodejs_buildpack
build-parameters:
builder: npm
ignore:
- node_modules
requires:
- name: DemoProject-service-uaa
- name: DemoProject-service-db
...
...
...

resources:
- type: org.cloudfoundry.managed-service
name: DemoProject-service-uaa
parameters:
service: xsuaa
service-plan: application
service-name: DemoProject-uaa
path: xs-security.json
...
...
...

`

---

Capability to generate MTA yaml and MTAD yaml


###### Method
buildV2(options? : MtaGeneratorSettings, logger? : IChildLogger) : Promise;
###### Description
Generate manifest for the project and the modules specified in .status_tracker file and create a mta.yaml and mtad.yaml file.
###### Parameters
- options: (Optional) MtaGeneratorSettings build options.
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- Promise
###### Example
`
const api = new ProjectImpl(projectPath);
await api.buildV2();
`
###### CLI
`
dev-project buildV2
`
###### Sample Output
`
_schema-version: '3.1'
ID: DemoProject
version: 1.0.0
description: A simple CAP project.
parameters:
enable-parallel-deployments: true
build-parameters:
before-all:
- builder: custom
commands:
- bash -c "cds compile srv --to xsuaa > xs-security.json"
- builder: custom
commands:
- npm install --production
- >-
bash -c "cds -v 2>/dev/null >/dev/null || npm install --no-save
@sap/cds-dk"
- npx cds build --production
modules:
- name: DemoProject-db-deployer
type: hdb
path: gen/db
parameters:
buildpack: nodejs_buildpack
build-parameters:
builder: npm
ignore:
- node_modules
requires:
- name: DemoProject-service-uaa
- name: DemoProject-service-db
...
...
...

resources:
- type: org.cloudfoundry.managed-service
name: DemoProject-service-uaa
parameters:
service: xsuaa
service-plan: application
service-name: DemoProject-uaa
path: xs-security.json
...
...
...

`
---

#### Build MTA Manifest content
###### Method
buildManifest(options? : MtaGeneratorSettings, logger? : IChildLogger) : Promise;
###### Description
Generate manifest for the project and all the modules and create a mta.yaml
###### Parameters
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of Project API.
###### returns
- Promise
###### Example
`
const api = new ProjectImpl(projectPath);
await api.buildManifest();
`
or

`
const api = new ProjectImpl(projectPath);
await api.buildManifest({ui5version: '1.1112.3', ui5theme: 'sap_belize'});
`
---


#### Get MTA Manifest content
###### Method
getManifest(logger? : IChildLogger) : Promise;
###### Description
Get the content of the mta.yaml file.
###### Parameters
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of Project API.
###### returns
- Promise
###### CLI
`
./src/project-api/bin/dev-project show-manifest ../risk-management-example
`
###### Sample Output
`
_schema-version: '3.1'
ID: cpapp
version: 1.0.0
description: "A simple CAP project."
parameters:
enable-parallel-deployments: true

build-parameters:
before-all:
- builder: custom
commands:
- npm install --production
...
...

modules:
- name: cpapp-app
type: html5
path: app
build-parameters:
builder: custom
commands:
- bash build.sh
supported-platforms: []
build-result: dist
...
...

`
---

Deployment of MTAR to Cloud Foundry


###### Method
deploy(logger? : IChildLogger) : Promise;
###### Description
Deploy the generated .mtar file to currently targeted CF space.
###### Parameters
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- Promise
###### Example
`
const api = new ProjectImpl(projectPath);
await api.deploy();
`
###### CLI
Build and deploy in one step
`
dev-project deploy
`

---

Deployment of MTAR to Cloud Foundry

###### Method
deployV2(logger? : IChildLogger) : Promise;
###### Description
Generate the .mtar file based on contents of .status_tracker file and deploy to currently targeted CF space.
###### Parameters
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- Promise
###### Example
`
const api = new ProjectImpl(projectPath);
await api.deployV2();
`
###### CLI
Build and deploy in one step
`
dev-project deployV2
`

---

Get Project Overview URL

###### Method
getProjectOverviewURL(logger? : IChildLogger) : Promise;
###### Description
Get the Project Overview URL of application deployed to currently targeted CF space.
###### Parameters
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of Project API.
###### returns
- Promise
###### Example
`
const api = new ProjectImpl(projectPath);
const projectOverviewURL = await api.getProjectOverviewURL();
`
###### CLI
`
dev-project get-projectoverview-url
`
###### Sample Output
`
{
applicationOverviewURL :
}
`
---

Get Application Deployment Summary

###### Method
getApplicationDeploymentSummary(logger? : IChildLogger) : Promise<{ ProjectOverviewURL?: string; DeployedUTCTime?: String; } | undefined>;
###### Description
Get the Application Deployment Summary of application deployed to currently targeted CF space which contains ProjectOverviewURL and DeployedUTCTime.
###### Parameters
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of Project API.
###### returns
- Promise<{ ProjectOverviewURL?: string; DeployedUTCTime?: String; } | undefined>
###### Example
`
const api = new ProjectImpl(projectPath);
const applicationSummary = await api.getApplicationDeploymentSummary();
`
###### CLI
`
dev-project get-application-deployment-summary
`
###### Sample Output
`
{
applicationOverviewURL : ,
DeployedUTCTime :
}
`
---

Get Detail Information of Entities

#### Get Detail information
###### Method
getDetailInfo(type: ItemType, ref: string, entityPath?: string, logger? : IChildLogger) :Promise;
###### Description
Get additional detail information about a particular item.
###### Parameters
- type: ItemType type of the Item.
- ref: Unique reference of the Item.
- entityPath: (Optional) Path of the item.
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- Item or undefined

###### Example
`
import {ItemType} from "src/project-glue/ItemType.ts" //Optional
const api = new ProjectImpl(projectPath);
const entities = await api.getDetailInfo(type, ref, entityPath)
`
###### CLI
`
dev-project get-detail-info
`
###### Sample Output
`
{
"type": "com.sap.cds/Entity",
"name": "fioriApp",
"ref": "sap.ui.demoproject.fioriApp",
"path": "schema.cds",
"info": {
"ID": {
"@Core.Computed": true,
"key": true,
"type": "cds.UUID"
},
"title": {
"type": "cds.String",
"length": 100
},
"owner": {
"type": "cds.String"
},
"descr": {
"type": "cds.String"
},
"miti": {
"type": "cds.Association",
"target": "sap.ui.demo.ui5App"
},
"impact": {
"type": "cds.Integer"
},
"criticality": {
"type": "cds.Integer"
}
}
}
`

---

Get Data Information


###### Method
getDataInfo(data: any, mainEntityName?: string, logger? : IChildLogger): Promise;
###### Description
Read and parse an Excel data file (CSV or XML format), or generate the main entity for a data model.
###### Parameters
- data: Path of the data file, or a data model parsed from an Excel file.
- mainEntityName: (Optional) Name of the entity taken as the main entity.
- logger: (Optional) An instance of IChildLogger which can be implemented by consumers of this library.
###### returns
- Promise

###### Example
`
const api = new ProjectImpl(projectPath);
const data = await api.getDataInfo(filePath);
const dataWithMainEntity = await api.getDataInfo(data, 'mainEntity');
`
###### CLI
`
dev-project get-data-info
`
###### Sample Output
`
[
{
entity: "test",
labels: [
{ label: "ID", value: "ID" },
{ label: "Capex Request", value: "capex_request" },
{ label: "Total Cost", value: "total_cost" },
{ label: "Department", value: "department" },
],
props: [
{
name: "ID",
kind: "dataType",
type: "UUID",
key: "true",
isComputed: "true",
},
{
name: "capex_request",
kind: "dataType",
type: "Integer",
key: "false",
},
{
name: "total_cost",
kind: "dataType",
type: "Integer",
key: "false"
},
{
name: "department",
kind: "dataType",
type: "String",
key: "false"
},
],
values: [
["2d22e87a-4a74-43e3-8f0c-fa9de4c1d008", "1", "1000000", "Technology"],
["d6a88765-b2a1-4c4a-916d-a10c5d286b53", "2", "1500000", "Products"],
["66c76a6b-da32-41ff-89e8-bd38c787bd86", "3", "2000000", "Technology"],
],
dbProps: ["ID", "capex_request", "total_cost", "department"],
},
]
``
---