docs: more content

docs/_sidebar.md

@@ -1,5 +1,6 @@
 * [Home](/)
 * [User Guide](guide/readme.md "Describes all the RPA CLI concepts.")
+* [Concepts](concepts.md)
 * [Command Reference](reference.md "Describes the latest version of the RPA CLI in detail and provides basic syntax, options, and usage examples for each operation.")
 * [Security](security.md)
 * [FAQ](faq.md "Frequently asked questions")

docs/guide/_sidebar.md

@@ -6,6 +6,8 @@
   * [Managing environments](guide/environment.md)
   * [Managing package sources](guide/package-source.md)
   * [Managing packages](guide/package.md)
+  * [Using executeScript](guide/execute-script.md)
+* [Concepts](concepts.md)
 * [Security](security.md)
 * [Command Reference](reference.md "Describes the latest version of the RPA CLI in detail and provides basic syntax, options, and usage examples for each operation.")
 * [FAQ](faq.md "Frequently asked questions")

docs/guide/deploy.md

@@ -0,0 +1 @@
+# Deploying the project

docs/guide/environment.md

@@ -18,7 +18,7 @@ These prompts can be bypassed if you provide all the options upfront, such as th
 rpa env new [alias] --url [url] --region [region] --tenant [tenant] --username [username] --password [password]
 ```
 
-The above command updates a configuration file named `[project_name].rpa.json` adding an *environments* property, where `[project_name]` is the project name, `[alias]` is the specified environment alias.
+The above command updates the configuration file named `[project_name].rpa.json` adding an *environments* property, where `[project_name]` is the project name, `[alias]` is the specified environment alias.
 ```json
 {
   ...
@@ -33,6 +33,8 @@ The above command updates a configuration file named `[project_name].rpa.json` a
 }
 ```
 
+!> **Warning**: the `[alias]` should be unique among [package source](guide/package-source.md) aliases and environment aliases.
+
 ### Options
 #### Url
 The IBM® RPA API URL of the server. 
@@ -54,4 +56,4 @@ The credentials to establish a connection to the environment. These are not stor
 
 # Next steps
 * [Managing package sources](guide/package-source.md)
-* [Deploying](guide/package-source.md) your project to an environment.
+* [Deploying](guide/deploy.md) your project to an environment.

docs/guide/execute-script.md

@@ -0,0 +1,80 @@
+# Using executeScript commands
+This guide describes how to use [executeScript](https://www.ibm.com/docs/en/rpa/23.0?topic=general-execute-script) commands so you can take advantage of the [build](reference.md#rpa-build) process to deploy [robots](guide/robot.md) - and not WAL scripts.
+
+## Context
+Currently, IBM® RPA does not group WAL files into projects. The Studio treats each WAL file independently and you can only publish/download one WAL file at a time. Studio treats WAL files independently because it treats them as robots, but WAL files are usually used as source code files from RPA developers, and a robot is usually composed of multiple WAL files.
+
+RPA CLI changes that concept. For RPA CLI, WAL files are source code files, not robots. Robots are the output of the build process. The build process outputs one or more robots, dependending on the *robots* property in the configuration file `[name].rpa.json`, where `[name]` is the project name.
+
+## Referencing WAL files
+The [build](reference.md#rpa-build) process expects [executeScript](https://www.ibm.com/docs/en/rpa/23.0?topic=general-execute-script) commands to reference WAL files like so: `executeScript --name "${workingDirectory}/[path_of_the_file]"`.
+
+### `${workingDirectory}`
+ `${workingDirectory}` is a *String* WAL variable type and its value should be the current local working directory. The build process injects code to the **main** WAL file **at runtime** to change the value of `${workingDirectory}` accordingly.
+
+When you create [robots](guide/robot.md) using *templates*, the initial WAL code structure is defined for you alongside with `${workingDirectory}` variable. The following is a template example for unattended.
+
+```
+defVar --name workingDirectory --type String
+//************************************
+//Template for a unattended
+//- Continue your logic from line 16.
+//************************************
+//Set the working directory where all local .wal files are located. Always use 'workingDirectory' variable in the 'executeScript' to reference the scripts.
+//- The build process will ignore 'executeScripts' that do not reference local .wal files using 'workingDirectory'.
+//- DO NOT publish or use published scripts in the 'executeScript'. The build process will buil ONE script with all the local referenced dependencies.
+//- Also, this will ensure your dev team only has to change one variable (workingDirectory) to run the project.
+//- If you call an 'executeScript', always pass the 'workingDirectory' variable as a parameter, so you do not need to set in every script.
+//- To store the source code .wal files, use GIT. Do not use the Control Center to store the .wal files.
+setVarIf --variablename "${workingDirectory}" --value "C:\\Users\\002742631\\Desktop\\Assistant" --left "${workingDirectory}" --operator "Is_Null_Or_Empty" --comment "The build process will inject the correct value for \'workingDirectory\' at runtime."
+onError --label HandleErrorWrapper
+//TODO: write the rest of your logic from here
+beginSub --name HandleErrorWrapper
+	goSub --label HandleError
+	recover
+endSub
+beginSub --name HandleError
+//TODO: handle the error
+endSub
+```
+<img src="_assets/template.png"/>
+
+### Path of the WAL file
+After the `${workingDirectory}` variable, you need to specify the file path within the local working directory. The path can contain child directories as well. Here are a few examples.
+
+The *Assistant* working directory structure:
+```
+├── Assistant
+│   ├── packages
+│   │   ├── Joba_Security.wal
+│   ├── skills
+│   │   ├── Assistant_OrangeHRM.wal
+│   ├── Assistant.wal
+│   └── Assistant_Thanks.wal
+└──
+```
+* Assistant_Thanks.wal: `executeScript --name "${workingDirectory}/Assistant_Thanks.wal"`
+* Assistant_OrangeHRM.wal: `executeScript --name "${workingDirectory}/skills/Assistant_OrangeHRM.wal"`
+* Joba_Security.wal: `executeScript --name "${workingDirectory}/packages/Joba_Security.wal"`
+
+## Ignored references
+Any [executeScript](https://www.ibm.com/docs/en/rpa/23.0?topic=general-execute-script) that does not follow the above pattern is ignored by the [build](reference.md#rpa-build) process. Which might mean that the deployed robot is not self-contained, requiring you to manually publish the other WAL scripts. Examples of ignored references.
+
+* Full path of the wal file: `executeScript --name "c:/Asssistant/packages/Joba_Security.wal"`
+* Only variable: `executeScript --name "${filePath}"`
+* Only script name without file extension: `executeScript --name Joba_Security`
+
+## Performance
+A common practice established for RPA developers using IBM® RPA is to reference scripts using **only** the `--name` parameter - and not specifying the `--version` parameter. This means that, at runtime, IBM® RPA fetches the script version marked as *production*. Since developers can change the *production* version at any time, even during bot execution, IBM® RPA **always** makes a HTTP request to fetch the script. The consequence of this behavior is fragile and slow robots.
+
+Imagine the following robot
+```
+defVar --name i --type Numeric
+for --variable ${i} --from 1 --to 1000 --step 1
+	executeScript --name Joba_Security
+next
+```
+
+It will make 1000 HTTP requests to fech *Joba_Security* script. It does not cache the script because the *production* version can be changed at any point by the developer. Obviously the above example is an exageration, but how many loops do you have that reference [executeScript](https://www.ibm.com/docs/en/rpa/23.0?topic=general-execute-script) commands without `--version`?
+
+> RPA CLI solves the performance problem by bundling WAL script reference into the robot - the **main** WAL file - through the [build](reference.md#rpa-build) process. At runtime, IBM® RPA only fetches 1 script, the **main** one. The other references are already available and do not need to be fetched.

docs/guide/package-source.md

@@ -1,5 +1,55 @@
 # Managing package sources
-*in progress...*
+Package source is not a concept defined in IBM® RPA. Package sources are package repositories from where you can install packages to your project. RPA CLI uses tenants as package sources. Please, read the [package source concept](concepts.md#package-source) explanation to understand the definition of package sources in the context of RPA CLI.
+
+## Prerequisites
+To issue `rpa package source` commands you need to have a project configuration file within the working directory. See [managing projects](guide/project.md) section.
+
+## Configuring a package source
+Issue the following command to configure a package source, replacing `[alias]` with any name you like to call this package source.
+
+```bash
+rpa package source [alias]
+```
+The above command will prompt you for additional information about the package source, such as *url*, *region*, *tenant*, *user name*, and *password*.
+<img src="_assets/rpa-package-source.gif"/>
+
+These prompts can be bypassed if you provide all the options upfront, such as the following command.
+```bash
+rpa package source [alias] --url [url] --region [region] --tenant [tenant] --username [username] --password [password]
+```
+
+The above command creates a package source configuration file named `[project_name].sources.json`, where `[project_name]` is the project name, `[alias]` is the specified package source alias.
+```json
+{
+  "[alias]": {
+    "code": [tenant_code],
+    "name": "[tenant_name]",
+    "region": "[region]",
+    "address": "[url]"
+  }
+}
+```
+
+!> **Warning**: the `[alias]` should be unique among [environment](guide/environment.md) aliases and package source aliases.
+
+### Options
+#### Url
+The IBM® RPA API URL of the server. 
+
+##### SaaS
+The URL option is usually `https://[region]api.[domain]/v1.0/`, for example `https://us1api.wdgautomation.com/v1.0/`. But RPA CLI already knows the SaaS APIs and you can just provide `--url default`.
+
+##### On-Premise
+The URL option is your API server URL followed by `/v1.0/`. For example, if your API server is `https://192.123.654`, then the URL should be `https://192.123.654/v1.0/`.
+
+#### Region
+The region option is only applicable in SaaS. It's one of the following values: *AP1*, *BR1*, *BR2*, *EU1*, *UK1*, *US1*. See [understanding tenants and regions](https://www.ibm.com/docs/en/rpa/23.0?topic=client-prerequisites-install#understanding-tenants-and-regions) for more details.
+
+#### Tenant
+The tenant option is the tenant **code**. See [getting your tenant code](https://www.ibm.com/docs/en/rpa/23.0?topic=client-prerequisites-install#getting-your-tenant-code) for more details.
+
+#### User name and password
+The credentials to establish a connection to the package source. These are not stored in the `[project_name].sources.json` configuration file. The credentials are not stored anywhere. Please refer to the [security](security.md) section for more information.
 
 # Next Steps
 * Install, uninstall, update, and restore [packages](guide/package.md).

docs/guide/package.md

@@ -1,2 +1,89 @@
 # Managing packages
-*in progress...*
+Package is not a concept defined in IBM® RPA. Packages are reusable libraries that you can add as a dependency to your RPA projects. Please, read the [package concept](concepts.md#package) explanation to understand the definition of packages in the context of RPA CLI.
+
+## Prerequisites
+To issue `rpa package` commands you need to have
+* a project configuration file within the working directory - see [managing projects](guide/project.md) section
+* a package source configuration file within the working directory - see [managing package sources](guide/package-source.md).
+
+## Installing packages
+Issue the following command to install the **latest** version of a package, replacing `[name]` with the package name.
+```bash
+rpa package install [name]
+```
+
+The command also support *wildcard* to install several packages at once, for example `rpa package install Security*` installs every package that starts with *Security*.
+
+To install a specific version, use the `--version` option.
+```bash
+rpa package install [name] --version [version]
+```
+
+By default, the command searches for packages in every configured [package source](guide/package-source.md). To install from a specific package source, use the `--source` option.
+```bash
+rpa package install [name] --source [source]
+```
+
+The above commands update the configuration file named `[project_name].rpa.json` adding a *packages* property, where `[project_name]` is the project name, `[package_name]` is the name of the package, and `[package_version]` is the version of the package.
+
+```json
+...
+"packages": {
+    "[package_name]": [package_version]
+  },
+```
+
+The commands also creates a `/packages/` directory within the working directory and downloads the WAL file named `[name].wal`, where `[name]` is the package name.
+
+## Uninstalling packages
+Issue the following command to uninstall a package, replacing `[name]` with the package name.
+
+```bash
+rpa package uninstall [name]
+```
+
+The command also support *wildcard* to uninstall several packages at once, for example `rpa package uninstall Security*` uninstalls every package that starts with *Security*.
+
+The above command updates the configuration file named `[project_name].rpa.json` removing the package from the *packages* property, where `[project_name]` is the project name.
+
+The command also deletes the WAL file named `[name].wal` from the `/packages/` directory, where `[name]` is the package name.
+
+> References to the package are not removed from WAL files.
+
+## Updating packages
+Issue the following command to update the package to its **latest** version, replacing `[name]` with the package name.
+```bash
+rpa package update [name]
+```
+
+To update to a specific version, use the `--version` option.
+```bash
+rpa package update [name] --version [version]
+```
+
+By default, the command searches for packages' updates in every configured [package source](guide/package-source.md). To update from a specific package source, use the `--source` option.
+```bash
+rpa package update [name] --source [source]
+```
+
+The above command updates the configuration file named `[project_name].rpa.json`, where `[project_name]` is the project name.
+
+## Restoring packages
+Issue the following command to restore packages.
+```bash
+rpa package restore
+```
+
+The above command creates a `/packages/` directory within the working directory and downloads all packages specified in the configuration file named `[project_name].rpa.json` *packages* property where `[project_name]` is the project name.
+
+## GIT
+Packages do not need to be committed to the source code since you can [restore](guide/package.md#restoring-packages) them at any point. It's recommended that you add the following line to the [.gitignore](https://git-scm.com/docs/gitignore) file.
+
+```
+packages/
+```
+
+> You can issue the [rpa git config](reference.md#rpa-git) command to configure that automatically.
+
+# Next steps
+* [Referencing packages](guide/execute-script.md) in WAL files.

docs/guide/robot.md

@@ -11,7 +11,7 @@ Issue the following command to create a robot within the working directory, repl
 rpa bot new [name] --template [template]
 ```
 
-The above command updates a configuration file named `[project_name].rpa.json` adding a *robots* property, where `[project_name]` is the project name, `[name]` is the specified robot name, and `[type]` is derived from the specified `[template]`.
+The above command updates the configuration file named `[project_name].rpa.json` adding a *robots* property, where `[project_name]` is the project name, `[name]` is the specified robot name, and `[type]` is derived from the specified `[template]`.
 ```json
 {
   "description": "[project_name]",

docs/index.html

@@ -19,13 +19,15 @@
       coverpage: true,
       loadSidebar: true,
       search: 'auto',
-      themeColor: '#E57A44'
+      themeColor: '#E57A44',
+      ga: 'G-4W227SRJTC'
     }
   </script>
   <!-- Docsify v4 -->
   <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
   <script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/[email protected]/components/prism-json.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>
   <script src="_assets/prism-rpa.js"></script>
   <!--<script src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js" type="text/javascript"></script>-->
 </body>

docs/reference.md

@@ -16,5 +16,11 @@ The IBM® RPA Command Line Interface (RPA CLI) is an *unofficial* tool that prov
 ## `rpa build`
 *in progress...*
 
+## `rpa deploy`
+*in progress...*
+
 ## `rpa pull`
+*in progress...*
+
+## `rpa git`
 *in progress...*