Initial Setup

Product Specifics / Service Guide Template

This chapter summarizes the tasks that need to be performed when setting up the service in a subaccount and enabling it to be consumed by a target application. These tasks include:

• Creating and binding a service instance (required for all services)
• Setting up destinations (only in some services)
• Setting up roles, authorizations, permissions, backend systems and others (only in some services)

These tasks are typically done in the SAP BTP Cockpit or a console tool (CLI/kyma console/cubectl, etc.)

Basic Considerations

The following questions might help you prepare the content for this chapter:

• Which environment(s) does your service run in? Is it available in more than one environment?
• Which standard steps (creating and binding a service instance) does the customer need to enable your service in his/her subaccount? (Hint: The exact steps are standard per each environment.).
• (Optional) How is the service enabled in a multi-target application?

• Does the user need to do further steps, such as:
• Create destinations?
• Set up backend systems?
• Add a configuration file, for example, a configuration JSON?
• Configure roles/role collections, assign permissions, scopes
• Does the service require the application developer to have a particular role assigned?
• Does your service bring a library?
• What kind of library is it (Java/NodeJS)? How is the library added to your project?
• Is there library documentation that you can link to, for example, Javadoc?
• Are there any other one-time setup steps that need to be completed before the service can be used by the application developer in the target application?

Usage of Multiple Topics

You can include all information in one topic called "Initial Setup" or create multiple child topics for the different setup tasks.

Topic Content

Title: Initial Setup

Use "Initial Setup" as title of your (root) topic. Do not replace it with another title.

Multiple topics

If you provide one topic for each task that you want to describe, use the task as topic title. Group all of these topics under the root topic "Initial Setup".

Introduction (without section title)

Use the following standard formulation to introduce the topic:

You can get started with <service name> using the standard procedures for SAP BTP Cloud Foundry/Kyma/Neo environment.

Prerequisites

Use the following standard formulation: You have set up your global account and at least one subaccount on SAP BTP. For an overview of the required steps, see Getting Started in the Cloud Foundry Environment/Getting Started in the Kyma Environment/Getting Started in the Neo Environment

Mention other services that must have been enabled (for example, WebIDE) and other components that must be available in the subaccount, if applicable.

Mention all further products that the customer needs to have (on-premise systems, databases, user stores, certificates, hardware, licenses, and so on).

Enabling the Service

This information is mandatory and can be provided as section in the "Initial Setup" topic or as separate subtopic. Include here all standard steps (creating and binding a service instance) and service-specific ones (destinations, configurations, role collections, etc.) if there are such.

Use the following standard formulation to introduce the topic:

Enable <service name> using the standard procedures for SAP BTP Cloud Foundry/Neo/Kyma environment.

Standard formulation for the steps:

1. Create a service instance in the Cloud Foundry/Kyma environment.
2. You can then bind the service instance to your application, or you can create a service key to communicate directly with the service instance.

Link to the following sections in the central SAP BTP documentation:

Example: Job Scheduling Service: Initial Setup section (info: Job Scheduling service is available in both the Kyma and Cloud Foundry environment).

Instance Sharing Between Environments

Add this information only if your service supports instance sharing between the Kyma and Cloud Foundry environments.

Use the standard formulation below:

You can re-use the created instance between the Kyma and Cloud Foundry environment.

If there are any service specifics regarding sharing of this service instance, describe them in your Administration section.

Example: SAP Credential Store: Share, Unshare, and Authorize a Service Instance.

Neo Environment

For the Neo environment, use the following standard formulation:

To use the <service name> service, you must enable it for your subaccount. For more information, see Using Services in the Neo Environment.

Enabling the Service in Multi-Target Applications

For multi-target applications, service instance creation and service binding can be done using the mtad.yaml file.

Add the following link for more information:

• Defining MTA Deployment Descriptors for Cloud Foundry

Setting Up Connectivity (if applicable)

Use this section if setting up connectivity/destinations is part of the service-specific steps for initial setup. You can also use a separate topic under the root topic "Initial Setup".

Use the following standard formulations:

• Set up a connection to <xy>.
• Create the following destination(s):

Link to the following section in the central SAP BTP documentation:

• Managing Destinations

Integration with another system

Some services can be integrated with another system, which means that there are multiple steps to be performed in the BTP and in the target system. In this case:

• Do not describe these tasks in the topic "Initial Setup", but describe them in the chapter "Integrating the Service with <System Name>"
• In this section set a link to the topic "Integrating the Service with <System Name>" (for multiple topics to the root topic of the chapter "Integrating the Service").

Setting Up Role Collections

Create this section/dedicated topic if setting up role collections (or roles) is part of your service-specific initial setup.

Only describe the tasks that enable the developer of the application to consume the service. Do not describe configuration tasks to be performed by the administrator of the application. These configuration tasks are described in Configuration.

Refer readers to more information about roles as follows:

• Building Roles and Role Collections for Applications (for the Cloud Foundry environment)
• Managing Roles (for the Neo environment)

Adding Libraries

Create this section/dedicated topic if your service provides a consumption library.

Explain how to add the library as a dependency to your project. You can, for example, provide a code sample of the pom.xml file. Here’s an example:

Add a link to the library documentation. For Java libraries, the documentation can be extracted as Javadoc and made available on the SAP Help Portal. You can find an example on the product page of the Unit of Measure service under Java Library Documentation.