initial content commit

Author: qmacro

README.md

@@ -1,41 +1,56 @@
-# SAP-samples/repository-template
-This default template for SAP Samples repositories includes files for README, LICENSE, and .reuse/dep5. All repositories on github.com/SAP-samples will be created based on this template.
+[![REUSE status](https://api.reuse.software/badge/github.com/SAP-samples/cap-service-integration-codejam)](https://api.reuse.software/info/github.com/SAP-samples/cap-service-integration-codejam)
 
-# Containing Files
+# Service integration with SAP Cloud Application Programming Model
 
-1. The LICENSE file:
-In most cases, the license for SAP sample projects is `Apache 2.0`.
+## Description
 
-2. The .reuse/dep5 file: 
-The [Reuse Tool](https://reuse.software/) must be used for your samples project. You can find the .reuse/dep5 in the project initial. Please replace the parts inside the single angle quotation marks < > by the specific information for your repository.
+This repository contains the material for the "Service Consumption with the SAP Cloud Application Programming Model" CodeJam, brought to you by the Developer Advocates at SAP.
 
-3. The README.md file (this file):
-Please edit this file as it is the primary description file for your project. You can find some placeholder titles for sections below.
+## Overview
 
-# [Title]
-<!-- Please include descriptive title -->
+This CodeJam introduces attendees to service integration with the SAP Cloud Application Programming Model (CAP). Specifically, the Node.js flavor of CAP is used.
 
-<!--- Register repository https://api.reuse.software/register, then add REUSE badge:
-[![REUSE status](https://api.reuse.software/badge/github.com/SAP-samples/REPO-NAME)](https://api.reuse.software/info/github.com/SAP-samples/REPO-NAME)
--->
+## About this CodeJam
 
-## Description
-<!-- Please include SEO-friendly description -->
+During this CodeJam, you'll become acquainted with how external services can be integrated and consumed from within a CAP project. You'll also understand about how event-based data federation can work. In working through this CodeJam you'll also become familiar with how the SAP Cloud SDK covers connectivity and destinations, supporting such integration scenarios with CAP. 
+
+## Session prerequisites
+
+In order to get the most from this CodeJam, and to be able to work through the exercises, there are certain prerequisites that you must have sorted out before the day of the CodeJam.
+
+The prerequisites are detailed in a separate [prerequisites](prerequisites.md) file. Please ensure you have everything ready before attending the CodeJam.
+
+## Exercises
 
-## Requirements
+These are the exercises, each in their own directory, sometimes with supporting files and scripts. We will work through the exercises in the order shown here. From a session flow perspective, we are taking the "coordinated" approach:
 
-## Download and Installation
+The instructor will set you off on the first exercise, and that's the only one you should do; if you finish before others, there are some questions at the end of the exercise for you to ponder. Do not proceed to the next exercise until the instructor tells you to do so.
 
-## Known Issues
-<!-- You may simply state "No known issues. -->
+> The exercises are written in a conversational way; this is so that they have enough context and information to be completed outside the hands-on session itself. To help you navigate and find what you have to actually do next, there are pointers like this 👉 throughout that indicate the things you have to actually do (as opposed to just read for background information).
+
+1. [Set up your workspace](exercises/01-set-up-workspace/)
+1. [Explore the basic service](exercises/02-explore-basic-service/)
+1. [Import an OData service definition](exercises/03-import-odata-api/)
+1. [Understand service mocking](exercises/04-understand-service-mocking/)
+1. [Add test data for the mocked external service](exercises/05-add-test-data/)
+1. [Mock external service in a separate process](exercises/06-mock-separate-process/)
+1. [Add CDS definitions to integrate services](exercises/07-add-cds-definitions/)
+1. [Introduce SAP Cloud SDK](exercises/08-introduce-sap-cloud-sdk/)
+1. [Set up the real remote system configuration](exercises/09-set-up-remote-system-configuration/)
+1. [Run the service with real remote delegation](exercises/10-run-with-real-remote-delegation/)
+
+## Feedback
+
+If you can spare a couple of minutes at the end of the session, please help us improve for next time by providing some feedback.
+
+Simply use this [Give Feedback](https://github.com/SAP-samples/cap-service-integration-codejam/issues/new?assignees=&labels=feedback&template=session-feedback-template.md&title=Session%20Feedback) link to create a special "feedback" issue, and follow the instructions in there.
+
+Thank you!
 
 ## How to obtain support
-[Create an issue](https://github.com/SAP-samples/<repository-name>/issues) in this repository if you find a bug or have questions about the content.
- 
-For additional support, [ask a question in SAP Community](https://answers.sap.com/questions/ask.html).
 
-## Contributing
-If you wish to contribute code, offer fixes or improvements, please send a pull request. Due to legal reasons, contributors will be asked to accept a DCO when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
+Support for the content in this repository is available during the actual time of the CodeJam event for which this content has been designed.
 
 ## License
-Copyright (c) 2023 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the [LICENSE](LICENSE) file.
+
+Copyright (c) 2023 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the [LICENSE](LICENSES/Apache-2.0.txt) file.

exercises/01-set-up-workspace/README.md

@@ -0,0 +1,128 @@
+# Exercise 01 - Set up your workspace
+
+At the end of this exercise, you'll have an environment in which to work for the duration of this CodeJam, and the contents of this repository ready to use.
+
+## Set up the environment and clone this repository
+
+To have the building blocks for this CodeJam ready to use, you'll need to clone this CodeJam repository and have the contents available in the workspace that you chose in the [prerequisites](../../prerequisites.md). Your workspace is either going to be a Dev Space in the SAP Business Application Studio (the "primary environment"), or VS Code with a dev container (the "alternative environment").
+
+Follow one of the two subsections here, as appropriate: either for a [primary environment](#primary-environment-a-dev-space-in-the-sap-business-application-studio) or for an [alternative environment](#alternative-environment-vs-code-and-a-container-image).
+
+### Primary environment: A Dev Space in the SAP Business Application Studio
+
+_Follow the "Alternative environment" subsection below if you want to use VS Code and a container image._
+
+#### Create a Dev Space
+
+👉 Via your subscription to the SAP Business Application Studio, create a new Dev Space, choosing the "Full Stack Cloud Application" type, and then make sure it's started up:
+
+![Setting up a dev space](assets/create-full-stack-cloud-application-dev-space.png)
+
+Choosing the "Full Stack Cloud Application" brings in some predefined extensions, as you can see from the screenshot, including a CDS Graphical Modeler and the CAP Tools. 
+
+> You may need to stop existing Dev Spaces to use this one, depending on your subscription access.
+
+#### Clone this repository
+
+👉 Once the Dev Space is started and you're in it, use the "Clone from Git" option in the "Get Started" screen that appears, to clone this repository, following the subsequent prompts to open the cloned repository (at which point your Dev Space will restart):
+
+![Cloning the repo](assets/dev-space-git-clone.png)
+
+#### Manually install the OData CSDL Modeler extension
+
+The final step to set up your Dev Space for the CodeJam is to manually install another extension, which is not yet available as standard in any Dev Space type. This is the [OData CSDL Modeler](https://marketplace.visualstudio.com/items?itemName=SAPSE.vsc-extension-odata-csdl-modeler), which is similar to the CDS Graphical Modeler extension, except that instead of displaying CDS definitions in a graphical representation, it can display OData definitions (EDMX metadata files) in a graphical representation.
+
+> The "Extensions" perspective in the SAP Business Application Studio's Dev Spaces can be used to install extensions comfortably, but only those available on the [Open VSX Registry](https://open-vsx.org/). The OData CSDL Modeler extension is currently only available on the official Microsoft Visual Studio Marketplace.
+
+👉 Go to the [OData CSDL Modeler](https://marketplace.visualstudio.com/items?itemName=SAPSE.vsc-extension-odata-csdl-modeler) page in the Microsoft Visual Studio Marketplace and download it with the "Download Extension" facility as highlighted here:
+
+![Download Extension from Microsoft Visual Studio Marketplace](assets/download-extension.png)
+
+👉 Once the file is available on your local machine, drag it to the Dev Space's "Explorer" perspective window to upload it to your Dev Space. Then, use the context menu on the file and choose "Install Extension VSIX":
+
+![Installing the extension VSIX](assets/install-extension-vsix.png)
+
+> Once installed, you can safely delete the file from the Explorer.
+
+You can check that the extension is indeed installed, by selecting the "Extensions" perspective, where you'll see it listed:
+
+![the CSDL extension listed](assets/extension-installed.png)
+
+### Alternative environment: VS Code and a container image
+
+_Follow the "Primary environment" section above if you want to use a Dev Space in the SAP Business Application Studio._
+
+👉 At a command prompt on your local machine, clone this repository into a directory of your choice, and then open VS Code, pointing to that newly cloned repository's directory:
+
+```bash
+git clone https://github.com/SAP-samples/cap-service-integration-codejam
+code cap-service-integration-codejam
+```
+
+Once VS Code has started, and opened the directory, it should notice the [dev container configuration file](../../.devcontainer/devcontainer.json) (in the [.devcontainer/](../../.devcontainer/) directory) and ask you if you want to "reopen the folder in a container", as shown in the screenshot. Confirm that you want to, by selecting the default answer "Reopen in Container". 
+
+![The dialog prompting you to "Reopen in Container"](assets/reopen-in-container.png)
+
+> If you're subsequently prompted to "manage unsafe repositories", please do so and follow the instructions.
+
+At this stage, once VS Code has reopened, you should be all set. You are ready to explore service integration with CAP in your dev container.
+
+> In case you noticed the manual installation step for the OData CSDL Modeler extension in the context of using a Dev Space (the primary environment instructions), and were wondering why there's no equivalent step here, it's because the extension identifier (`sapse.vsc-extension-odata-csdl-modeler`) is included in the [devcontainer.json](../../.devcontainer/devcontainer.json) file in the list of extensions to install into the dev container. Nice!
+
+## Install the CDS development kit
+
+_This and subsequent steps apply to both the primary and alternative environments._
+
+👉 Open a terminal, using "Terminal: Create New Terminal" in the Command Palette. At the prompt, install the CDS development kit globally, like this:
+
+```bash
+npm install --global @sap/cds-dk
+```
+
+> Having specified a "Full Stack Cloud Application" Dev Space type, this step isn't actually entirely necessary in the SAP Business Application Studio, because you get this tooling as standard (it's part of the "CAP Tools" extension that comes with the type selected), but you can run it anyway.
+
+You should see that the CDS development kit is installed.
+
+👉 Check the version:
+
+```bash
+cds v
+```
+
+Depending on your workspace, you'll see slightly different output, but it should generally look something like this:
+
+```text
+@sap/cds: 6.4.1
+@sap/cds-compiler: 3.5.4
+@sap/cds-dk: 6.4.1
+@sap/cds-dk (global): 6.4.1
+@sap/cds-foss: 4.0.0
+@sap/cds-mtx: -- missing --
+@sap/cds-mtxs: 1.4.4
+@sap/eslint-plugin-cds: 2.6.0
+Node.js: v18.13.0
+home: /usr/local/share/npm-global/lib/node_modules/@sap/cds-dk/node_modules/@sap/cds-dk
+```
+
+## Summary
+
+At this point you've got an environment in which to work through the rest of the exercises in this CodeJam, you've got the contents of the repository, and you have the CDS development kit installed and ready to use.
+
+## Further reading
+
+* [Developing inside a Container](https://code.visualstudio.com/docs/devcontainers/containers)
+* [Cloning repositories](https://help.sap.com/docs/SAP%20Business%20Application%20Studio/9d1db9835307451daa8c930fbd9ab264/7a68bfa7111b44f6b1e78b51e803238c.html) in SAP Business Application Studio
+* [The @sap/cds-dk package on NPM](https://www.npmjs.com/package/@sap/cds-dk)
+
+---
+
+## Questions
+
+If you finish earlier than your fellow participants, you might like to ponder these questions. There isn't always a single correct answer and there are no prizes - they're just to give you something else to think about.
+
+1. What are the advantages of using container images for development work? 
+1. What is the difference between the `@sap/cds` and `@sap/cds-dk` packages?
+
+---
+
+[Next exercise](../02-explore-basic-service/)