@sap/subaccount-destination-service-provider

Overview

subaccount-destination-service-provider is an npm package that provides the APIs necessary for exposing subaccount destination systems and services.

Usage

To add this package as a dependency in your package.json file, under the "dependencies" section, add the following dependency: "@sap/subaccount-destination-service-provider": [Version]

APIs

This repository exposes APIs for the exploration of SAP systems and services that are consumed from the Business Application Studio (BAS) subaccount.

init

This API initializes a provider repository representing a given subaccount.

async init(): Promise<void>

throws ServiceProviderError: If there is an error, this throws a "ServiceProviderError" error message.
INTERNAL_ERROR: This error is displayed for any other exception.

getSystems

This API retrieves systems exposed by the subaccount.

async getSystems(filter?: Filter): Promise<ProviderSystem[]>

filter (this is optional): Only retrieves systems that comply with the given filter. throws ServiceProviderError: If there is an error, this throws a "ServiceProviderError" error message.
RETRIEVE_DATA: This error is displayed if data cannot be retrieved from the system.
INTERNAL_ERROR: This error is displayed for any other exception.

getServices

This API retrieves services exposed by a specific system.

async getServices(options?: Record<string, any>): Promise<Service[]>

options (this is optional): The following parameters are optional:
     credentials (this is optional): for services that require authentication.
     filter (this is optional): Used to filter for relevant services.
throws ServiceProviderError: If there is an error, this throws a "ServiceProviderError" error message.
     RETRIEVE_DATA: This error is displayed if data cannot be retrieved from the system.      INTERNAL_ERROR: This error is displayed for any other exception.

getMetadata

This API retrieves metadata exposed by a specific system.

async getMetadata( service: Service, encoding: EncodingMode, options?: Record<string, any> ): Promise<ServiceMetadata>

service: Defines the service from which the metadata will be retrieved.
encoding: Defines the required encoding requested by the consumer.
options (this is optional): The following parameters are optional:
     credentials (this is optional): for services that require authentication.
     filter (this is optional): Used to filter for relevant services.      relativeUrl (this is optional)*: for a non-full URL - provides the relative URL to the service.
throws ServiceProviderError: If there is an error, this throws a "ServiceProviderError" error message.
     RETRIEVE_DATA: This error is displayed if metadata cannot be retrieved from the service.
     *INTERNAL_ERROR*: This error is displayed for any other exception.

getAnnotations

This API retrieves an array of annotations exposed by a specific system.

async getAnnotations(service: Service, options?: Record<string, any>): Promise<Annotation[]

service: Defines the service from which the annotations will be retrieved.
options (this is optional): The following parameters are optional:
     credentials (this is optional): for services that require authentication.
throws ServiceProviderError: If there is an error, this throws a "ServiceProviderError" error message.
     RETRIEVE_DATA: This error is displayed if annotations cannot be retrieved from the service.
     INTERNAL_ERROR: This error is displayed for any other exception.

Examples

Initialize repository await saRepo.init();

List subaccount systems (destinations)
const saSystems = await saRepo.getSystems();

Create credentials object - Used to access a system or service that requires authentication.
const credentials = getCredentialsObject("username", "password");

Select a system and list the catalog services that it provides.
Note: Add credentials since the system needs authentication.
const saSelectedSystem = findByName(saSystems, "U1Y010_BASIC");
const saServices = await saSelectedSystem.getServices({credentials: credentials});

Create a filter object - Used to filter for required services.
const filter = getNewFilter("protocol", ["odatav2"]);

Select a service and consume the metadata and annotations that it provides.
Note: Add credentials since the system needs authentication.
const saSelectedService = findByName(saServices, "ZPAGE_BUILDER_CUST");
const saMetadata = await saSelectedSystem.getMetadata(saSelectedService, saProvider.EncodingMode.XML, {credentials: credentials, filter: filter});
const saAnnotations = await saSelectedSystem.getAnnotations(saSelectedService, {credentials: credentials});

credentials: An object that enables you to add credentials to your system request.
USER: system username
PSW: system password
Credentials can be built as follows:*
credentials = new Authentication(, );
filter: An object that enables you to filter for systems that you want to receive.
FILTER_KEY: (string) A key used to filter the list of systems.
FILTER_VALUES: (array of strings) accepted values of the filter key, separated by commas.
Filters can be built as follows:
filter = new Filter(new Map([[<FILTER_KEY>, <FILTER_VALUES>]]));

Git and GitHub

Open Git Bash, go to the local repository directory, and sync with the remote repository.
Develop in a Local branch.

Create a new descriptive branch git checkout -b my-local-branch-name
OR rename the previous one git branch -m my-local-branch-name.
Make sure my-local-branch-name is NOT master and that there is no existing branch with this name.

Sync with the remote repository.

Fetch the code from the master branch by running git fetch; git merge.

Make your local changes.

Run npm install to install dependencies.
Run npm run test to compile the TypeScript code to JavaScript and run tests.

Commit and push.

Do not push directly to master!!!
Commit your changes and push to create a new branch on GitHub by running git push origin my-local-branch-name
On consecutive commits DO NOT use commit amend. You should create a new commit and push to the same feature branch again. This will add an extra commit to your pull request and retrigger the voters.

Open a pull request.

Click 'New pull request' next to your branch.
Edit the pull request name with BLI or BCP. For example: "BLI DEVXCORE-123: my new feature" or "BCP 1670451810: Fix my bug".
A new branch (my-local-branch-name) is created in the GitHub repository.
The new code should enable all voters and code review to pass successfully.

Update the existing pull request.

Stage your changes and create a new commit.
Perform Git fetch.
Perform Git merge on origin/master - Merge your changes with the most updated master branch.
Push your changes to your my-local-branch-name (Git push origin my-local-branch-name).

Merge the pull request.

If all voters passed (XMake + JaaS Voter), click 'Merge pull request'.
If your pull request contains several commits, you combine them in one commit from GitHub by selecting the 'Confirm squash and merge' option from the Merge dropdown list.

Delete your branch.

After the merge is complete, go to Code > Branches.
Look for your merged pull request and click the delete branch icon.

Tests and Coverage

Run npm run test to run the unit tests written in Mocha and the coverage test.

Release

Bump the version in the "package.json" GitHub file.

Notes: Make sure to follow this versioning concept:

When providing new features (when releasing at the end of the sprint or when a new feature is ready), bump a major version (for example, from 1.1.0 to 1.2.0).
When providing a bug fix to an existing version ("hotfix"), bump a minor version (for example, from 1.1.0 to 1.1.1).