article by Frank Nimphius, July 2020
GIT is a free open source version control system available at https://git-scm.com/about/free-and-open-source.
This article does not explain GIT but shows how you can use GIT to version control Oracle Digital Assistant custom component service projects.
Also, in this article I propose a GIT repository structure that has directories built for each skill requiring custom components. This proposal is for custom components that should be deployed to the local component container in a skill. You would probably use a different code organization if components will be deployed to a remote repository.
For illustration purposes, this article uses Microsoft Visual Studio Code as a JavaScript IDE because it has GIT support built-in.
When you develop custom component services, you don't have any dependencies to a specific JavaScript IDE and can choose whatever you prefer. At least though you want to make sure that the IDE you use supports Node debugging. If you are experienced with GIT then you will be able to get away without GIT support in the IDE and use the command lie instead.
Organizing custom component projects for your Oracle Digital Assistant project
You can create a new GIT project from a command line or terminal, or use a graphical tool or interface. For this article I used a browser based user interface to create a new GIT project for the custom components I expect to write for a new Oracle Digital Assistant project.
As you can see in the image below, the GIT project has several directories created. Each directory has the name of the skill for which the custom components will be created. In addition, there is one directory for common custom components, which will be deployed to each and every skill in the Oracle Digital Assistant project.
Important! The outline of the GIT repository structure assumes that custom components will be deployed to the local skill containers. If you plan to deploy custom components on a remote server, not using the local skill container, then you could change the project layout to e.g. use a logical structure. You can also go for a hybrid approach in which you deploy skill dependent custom components to the local container and the common custom components to a remote container.
To copy the remote GIT repository to your local computer, you need to clone it. For this you copy either the HTTPS or SSH access to the project. Graphical user interfaces, like the one shown in above image, display a "clone" option for this.
Creating a local copy of the GIT repository
To develop custom components locally and to version control them in GIT, you need to have the following software installed
- Node and Node Package Manager (NPM). Its all in a single download from the Node website (https://nodejs.org/en/download/)
- GIT installed globally (https://git-scm.com/downloads)
- Oracle Bots-Node-SDK installed globally (https://github.com/oracle/bots-node-sdk)
- A JavaScript IDE, for example Microsoft Visual Studio Code (https://code.visualstudio.com/download)
To create a local copy of your GIT repository, you first need to follow the GIT or your Git repository provider's instructions for how to clone a project to contribute to it.
In this example, I am using a SSH access to the remote GIT repository from GIT installed on a MAC. To clone the remote project, issue the git clone <SSH URL> command.
When the process is completed, then your local computer owns an exact copy of the remote repository.
Notice the ".git" file, which keeps track of changes you apply to your local copy.
Creating a new custom component project
Let's assume the financial sample bot should be extended with a skill to handle mortgage loans. Certainly this will require backend integration for which custom components need to be built.
So, following the directory structure explained in the beginning of this article, create a new folder "MortgageLoan".
To create a custom component project, cd into the newly created folder. Then, issue npm init -y as a command.
This command creates a new package.json dependency file that ensures the Node project name to be copied from the parent folder.
Next, create a new custom component project using the Oracle Bots Node SDK. For this issue the following command: bots-node-sdk init —component-name LoanCalcuator . The command creates a new custom component project with an initial component named LoanCalculator.
Note that following the idea of creating a custom component package per each skill, you will be able later to create a deployable ".tgz" file just from this folder. Same when it comes to debugging custom components. You can navigate to this folder and then start the integrated Node server to run the component code.
Tutorials:
Building custom components: https://docs.oracle.com/en/cloud/paas/digital-assistant/tutorial-cc-dev/index.html
Local debugging of custom components: https://docs.oracle.com/en/cloud/paas/digital-assistant/tutorial-cc-debug/index.html
Open the project in your JavaScript IDE
If you open the custom component project in Microsoft Visual Studio Code, then, as shown in the image below, the tool automatically detects that the folder is GIT enabled and that it contains changed files or, as in this example, files that have been added but not yet versioned (indicated by the blue alert in the toolbar on the left).
Select the versioning icon in the toolbar to switch to the Versioning panel.
Click on the Plus icon to add the files to a group that you want to commit to the GIT repository
Next, provide a comment for the commit
Finally either press the checkmark icon or press cmd+enter (on a MAC) to commit the changes. A commit prepares local changes for publishing to the remote GIT repository. To save changes to the remote repository, you need to push the committed changes.
If then you start changing a file, like editing a custom component, the changes are again indicated in the toolbar.
You can switch to the versioning panel in Microsoft Visual Studio Code to see the changes that were applied to a file to either undo changes or commit them for a next push request to the remote rpository.
Viewing the changes in the remote repository
After refreshing the remote GIT repository, the new folder and folder structure become visible,
The file structure also contains a readme file added by the Oracle Bots Node SDK that contains useful commands to work with the SDK
What you should know
The Oracle Bots Node SDK adds all Node dependencies in the node_modules folders to the git ignore list.
This means that when you pull (download) a custom component project from a remote repository or when you upload a new, then no dependent node modules are contained. So when you pulled a new custom component project, you need to issue a npm install command from the component package folder to install the dependent node modules.
The dependent modules are only needed if you want to create a deployable custom component package or if you want to run the custom component locally for debugging or testing.
Related content
Hands-on: Building custom components
Hands-on: Custom component local debugging
TechExchange Quick-Tip: Customizing the Oracle Bots Node.js SDK Component Template
