Welcome to Office Kube Documentation!
Overview
Developer Workspaces
Artifact Generation
Task Developer Guide
Workflow.yml
- 1. Format
- 2. Use of Template Generators
  - 2.1. Generator Dependency
  - 2.2. Parameter Handling
Office Kube Task Libraries
- 1. Template Engine
- 2. AI Library
Applications
- Why to use Apps

Welcome to Office Kube Documentation!¶

Office Kube is a robust scalable platform that automates provisioning and configuration of workspaces based on your role. It also allows you to greatly automate activities ranging from a simple routine such as setting up a reminder to complex workflows that require various resources be it hardware resources such as computers and storage or properly configured software tools.

Overview¶

The Office Kube platform includes a number components that allow user activity automation. Each component is described in greater details below.

1. Workspace¶

When you create a workspace a dedicated instance of what could be thought as a virtual computer gets created in the Office Kube platform.

The instance has a number of components installed and configured on it:

Applications
User Interface
Project Repository
Authentication
Workflow Engine
Mechanics

Applications¶

Depending on your role, the workspace gets a number of applications (further refered as apps) set up.

There are apps included in every workspace. These are Terminal, File Browser, Midnight Commander, and htop (process viewer). Additional apps can be installed using the workspace toolbar (described in details below).

Every workspace includes the Robot Framework and a number of libraries for that framework. The framework and the libraries are used to automate user’s activities.

Our workspaces for developers include apps such Visual Studio Code and Swagger API Editor and additionally VS Code extensions and other tools specific to a developer’s role. For more details refer to our Developer Workspaces.

User Interface¶

For better user experience the workspace provides a toolbar which can be located at the bottom of a web-browser workspace window. The toolbar allows to search/execute/create task (menu Tasks), switch between applications (menu Navigate to) and get access to help/feedback and user’s profile.

https://officekube.io/images/toolbar/toolbar.png

Project Repository¶

By design, the Office Kube platform allows you to store your project in a git repository and every workspace has a default project location /work/project. This feature is optional and does not have to be used.

Authentication¶

Currently, there is a couple of ways with which you can register as a user - using your email address or your GitHub account. We are working on enabling more types of authentication.

Workflow Engine¶

One of the core components of the workspace is a so-called workflow engine that executes automation workflows/tasks on the workspace.

The engine functionality is utilized through the toolbar’s menu item Tasks.

Some Workspace Mechanics¶

Workspace State. By default, the workspace persists your tasks, projects, and other artifacts in folder /work. These artifacts constitute a workspace state. The state can be persisted using a feature Persistent Storage available when you create a workspace. Should the workspace get crashed unexpectadly it will get automatically recovered from the persistent storage.

Idle Time. If a user leaves the workspace inactive for some time, the workspace gets automatically shut down. Next time the user attempts to access the workspace it is automatically re-activated from the previously stored workspace state.

Workspace Power. Our workspaces are provisioned on hardware resources to provide adequate performance. We are actively working on giving an option to a user to deploy the workspace on resource with different performance profile including options of dedicated resources and/or own hardware. Please contact us (via Help -> Feedback) if you have any specific questions and/or suggestions.

In future versions we plan to introduce special purpose so-called tool workspaces. These workspaces have a set of tools installed on them and are intended to carry out specific operations. Users will be able to plug in such workspaces into their workflows to achieve greater level of automation for their individual/team/organization activities. More to come.

2. Workflows¶

As you work on projects the chances are you often perform similar (if not same) old tasks over and over again.

Many such activities can be automated in your workspace using workflows provided by the Office Kube platform.

The platform provides a searchable repository of tasks that can be leveraged in your workstream.

Tasks can be located using menu item Tasks -> Execute in the toolbar located at the bottom of a web-browser workspace window.

https://officekube.io/images/toolbar/task_execute.png

A Task Management dialog will pop up and guide you through a process of searching, viewing, and executing/scheduling a task.

https://officekube.io/images/toolbar/task_management_dlg_search.png

3. Apps¶

Workflows/tasks described earlier are used to automate user activities and are referred to as automation tasks.

The concept of workflows is leveraged to configure workspaces as well as to install and configure applications.

Whenever the workspace starts for the first time and depending on its type it can have one ore more apps bundled with the workspace.

Examples of bundled apps include Terminal, File Browser, Midnight Commander.

Additional apps can be installed from our app repository.

Each bundled app as well as the capability to install additional apps can be accessed vit the toolbar’s menu Apps.

https://officekube.io/images/toolbar/apps.png

Each app can be started/stopped from that menu using a toggle located next the app. Apps that have been installed (using the menu item Install a New App) can removed by clicking on the trash bin icon (also located next to the app).

4. Tool Workspaces¶

Often and in addition to your workspace, you might need to use other tools that have to be installed and configured as separate components.

The setup of such tools and their integration into your workflows are quite often complex and/or time consuming. Additionally, these tools usually require some ongoing maintenance.

You can greatly minimize all this effort by leveraging our tool workspaces that you can find in the same list of workspace templates available via our portal when you create a new workspace.

You can create tool workspaces and control their life cycle and use workflows from our workflow repository to leverage these workspaces in a fully automated way.

We constantly keep growing our repositories of workflows, tool workspaces, and apps and if you’d like us to add any additional tool workspaces and/or apps and/or contribute in development of workflows please drop us a note.

Developer Workspaces¶

By design our developer workspaces are built based on a technology stack. Currently available developer workspaces are java, node js (backend/react/angular), python, and golang.

It should be noted that it does not mean that once you provision a certain developer workspace you are constrained by a tech stack installed on it. You can always install any additional software.

Also, every workspace (including the developer versions) comes with pre-installed Node JS 16, JDK 11, and python 3.9 in case you need to execute any software that requires any of these runtimes.

In general, a developer workspace allows you to perform the following activities (without having to install any additional apps):

Generate, write, debug, and test code.
Write and execute different types of tests (unit, API/contract, integration).
Use tools workspaces (e.g. SonarQube, Storybook, etc) to perform tasks such as test code quality, vulnerability analysis, ui validation (for frontend developers), etc.
Package and deploy your application.
Generate/maintain documentation.

To accomplish all of the mentioned above tasks and applications can be used within the workspace (described in this guide).

Artifact Generation¶

Many activities require creation of file-based artifacts. Examples include office documents, files with source code, configuration files.

While the content of these artifacts varies going from one project to another, their structure in many cases remains very similar, if not the same.

In such cases productivity can be improved with the help of an artifact generator that uses a set of templates with a given structure and that allow for specific content.

Here are some examples where the use of the artifact generator helps boosting productivity:

Spreadsheets. In this scenario the generator is expected to produce a spreadsheet that implements a certain table-based algorithm. Examples are project ROI, expense report, project timeline, cashflow, balance sheet, loan amortization.
Code Snippet Generator. A number of software development tasks are very similar across different projects and technology stacks. Examples include loading/reading/writing configuration files in different formats, writing code connecting to the DB, implementing REST API endpoints, using logging library, adding security code for user authentication/authorization, adding code to use various protocols (e.g. oauth2), adding unit/integration tests. Additional examples can be found in projects such as JHipster.
Project Scaffolding. At the very start of an application development, the use of a generator that can create a project skeleton with many standard capabilities (e.g. security, db, API endpoints, logging, etc) can provide a significant boost.

The Office Kube platform includes a large number of tasks that help generate various artifacts. These tasks can be located using a menu item (from the toolbar) Tasks -> Execute and using a keyword generate along with other keyword specific to a problem domain or a type of generator (e.g. scaffolding).

Please try to find one (through the toolbar) that fits your purpose and if you don’t find one do not hesitate to contact us (Help -> Feedback).

Task Developer Guide¶

This section provides details around how to build, test, and publish your automation task.

The Office Kube platform leverages an open-source Robot Framework for task automation. The framework has a great user guide that can be referenced during development of your task.

The platform facilitates the entire development cycle of the task. At high level, the development entails:

Creating a task scaffolding
Building
Testing
Publishing

Each step is described in greater details below.

1. Create¶

To create a task scaffolding simply select Tasks -> Create menu item from the toolbar.

You will be prompted to populate two mandatory parameters task name and its description.

Optionally, you can also change a default value (home/me/project) for a path where a generated project scaffolding should be stored.

Proceed to the tab Execute and click Execute button to generate the scaffolding.

Once the Create workflow completes you should see files README.rst, robot.task, and workflow.yml in mentioned folder in your workspace.

Next, you open the folder in Visual Code Studio where the file README.rst should automatically get opened.

Under the hood, the workflow also creates a repository for your generated task with a default branch named main.

You can then proceed with following the readme file (using its quick start section) or open task.robot file (to start building the task) or continue reading this guide (to learn more details about task development).

2. Build¶

At high level, task development involves the following:

Identifying and using libraries.
Defining input parameters that your task may need.
Writing code.

Libraries¶

Capabilities of the Robot Framework can be extended with libraries that implement purpose specific keywords which can be used in your tasks.

Every workspace in the Office Kube platform is bundled with the following libraries:

All libraries built into the Robot Framework (Builtin, Collections, DateTime, Dialogs, OperatingSystem, Process, Remote, Screenshot, String, Telnet, XML).
Office Kube libraries: 1. Template Engine
Third-party libraries: RPA Framework, RESTinstance

The list provided above gets constantly extended. So, please check with this guide every time you need to write a task.

It should be noted that you could still install libraries not listed above in your workspace. However, if you intend your task to be used by other users the task will fail since those users’ workspaces will not have these additional libraries.

Additionally, the persisted workspace state does not include any of the additionally installed components in the workspace. So, should the workspace get restarted any such additional libraries would have to be re-installed.

If you do need a library not listed above please contact us (using the Help->Feedback menu item from the toolbar).

Task Input Parameters¶

For its proper execution your task may require some parameters. Some of these parameters might have to be populated by a user, some by the Office Kube platform.

For that the Office Kube platform uses a special file called workflow.yml. This file must reside in the same folder where your task is.

Specifics on the format of this fil and its used are described in detail in Workflow.yml

3. Test¶

A process of (unit) testing involves execution, reviewing the results, and, if needed, troubleshotting.

Execution¶

There are several ways in which you can execute your task.

Open a VS Code Terminal, switch to the directory where your task resides and execute:
```
robot task.robot
```

https://officekube.io/images/rpa/run_task_from_terminal.png

Open your task file in VS Code Editor and execute the task using a menu item Run located right above the line where your task is defined:

https://officekube.io/images/rpa/run_task_from_context_menu.png

Use an Interactive Live Console to exeecute either your entire task or its lines individually:

https://officekube.io/images/rpa/run_task_in_interactive_console.png

For example, to execute the generated task (also shown below) you can open the terminal and execute:

robot README.rst

*** Settings ***
Library     okgenerator.TemplateEngine

*** Variables ***
${sample_variable1} My OK Task
${sample_variable2} %{some_env_var}

*** Tasks ***
My First Office Kube Task
    Log to Console  \nCongratulations with successful creation of your first task ${sample_variable1}

Viewing Results¶

Execution of a task produces 3 files:

report.html - High level test report.
log.html - Detailed test execution log.
output.xml - Results in machine readable XML format.

The Office Kube automation includes the file report.html in its report.

Debugging¶

For debugging purpose and as can be seen in the screenshots above a menu item Debug from the context menu can be used to step through the task line by line.

Environment Variables¶

Sometimes a task needs to use environment variables for its proper execution (e.g. when need to use a user’s authentication token).

In this case you can, for example, create a shell script that will populate the necessary variables and then execute the task:

#!/bin/sh
export some_env_var=some_test_value
robot -V variables.yml task.robot

In the example above an environment variable some_env_var is populated with a value and the task is executed using the same robot command but with a command line argument -V that accepts a name of a file where task variables are defined in the yaml format. Below is the content of the variables.yml file for the task sample defined above:

sample_variable1: "My OK Task from the variables.yml"

4. Publish¶

When the task is created (using the Create menu item in the toolbar) a project with a repository is created in the Office Kube platform.

To make the task searchable and available for execution by all registered users you need to create a branch dev (for dev environment) or prd (for our production environment) and create a merge request to push the code into either/both of these branches.

When a user finds and selects the task in the Task Management dialog, tab Search, the content of the task’s file README.rst is rendered in the tab View of that dialog.

A recommended way to make the task ready and publish it is to::

Validate all input parameters that the task needs (workflow.yml). If there are any inputs to be populated by the user please make sure to populate proper attributes (description, usage, format) so that it makes the user’s job of populating the inputs easy.
Build and test the task (files task.robot)
Update the README.rst file. The description should clearly explain to the user what the task does and what output it produces.
Push changes to the task’s repository. The default repository branch is not. It is, however, is NOT used by the platform. To make the task available to the user the code of the ask must be pushed into the branch prd.

Prompt Task¶

A special kind of task called a prompt task can be built to leverage AI capabilities of the platform. This task should have its property type (in info section) set to prompt (not task).

All task parameters defined in section parameters are treated as prompt parameters.

The task has a mandatory component inputView.ejs - this is a template that should be written using EJS syntax. The purpose of the template is to present the prompt to a user in a format that would allow the user to conveniently populate those parameters that the task needs in order to produce an accurate and relevant response by the platform AI capability.

Another mandatory component is prompt.mustache - this is a mustache template of the prompt and is used by the platform to put together values of the parameters and the rest of the prompt. The prompt template should reference parameters in the form of {{{parameter_1}}}, {{{parameter_2}}}, etc. The platform uses the prompt to provide a user with an estimate for that prompt. While the prompt task developer does NOT have to use that template it is important that the actual prompt submitted to the platform AI service is as close as possible to the one provided in prompt.mustache (to ensure the accuracy of the cost estimate).

For the prompt task there is one special parameter called ok_prompt. This parameter is populated by the platform and is passed into the task.

An overall approach implemented by the platform as far as properly creating the prompt is as follows:

Render inputView.ejs to the user. The template is rendered as part of the prompt editor user interface that is included into the task toolbar.
The user populates all prompt parameters they are expected to.
The prompt editor collects the values (entered by the user) and stores them internally.
Once the user submits the prompt it is sent to the task along with all prompt parameters made available as task variables.

In the context of this approach it is important to note that whatever parameters your task needs the user to populate, their names must be defined in workflow.yml and referenced by exact same names in both inputView.ejs and prompt.mustache templates. Otherwise, the platform will NOT populate the prompt correctly.

Another important note to make is that the type of each prompt parameter defined in workflow.yml file and used in inputView.ejs must match.

For example, a parameter of type string (defined in workflow.yml) must be presented in inputView.ejs as a text box, a parameter of type string and with a property allowed_values set to at least 2 values must be presented as a single choice dropdown box, etc. Refer to section parameters for complete details on parameter definition.

The AI service supports regular prompts as well as so-called prompt chains which are recommended to use when the prompt is rather large (very detailed) in which case it is better to break them into small tasks that LLMs have a better performance handling.

In the prompt chain a keyword ```PROMPT should be used on a single line to separate tasks. In this case the AI service will submit each task to the LLM separately and will use an output of previous task as an input for next one.

Here is an example of 2 task prompt chain:

```PROMPT Describe task 1 ```PROMPT Describe task 2 that might need output from task 1

For the task to submit a prompt to the platform AI service, the task should utilize proper keywords provided by library AI Library. The following is an example on how to use a keyword Generate To Files provided by the library:

import okailibrary.PromptBasedTextGenerator

* Tasks * Generate Code Snippet

Generate To Files ${dest_dir} ${prompt} ${workflow_id} ${dest_map_file} ${code_language}

If your task needs to produce an output that should be rendered to the user, create a file output.json in the format { label1: content1, label2: content2 } and store it in the same folder where the task is. The workspace engine will pick up this file and return it to the workspace UI where it will be rendered in an html 2-column table (column for labels column for content) accordingly.

The following example illustrates the definition of workflow.yml, inputView.ejs, prompt.mustache, and task.robot (that generates output.json) for a prompt workflow.

workflow.yml:

info:
    name: Prompt Workflow
    id: com.officekube.platform.samplepromptworkflow
    type: prompt
    target: workspace

parameters:
  - name: ok_prompt
    displayed: no
    description: Prompt used to generate the skeleton.
    type: string
    required: yes
    masked: no

  - name: code_language
    displayed: no
    type: string
    allowed_values:
    - value1
    - value2
    required: yes
    masked: no

  - name: single_choice_param
    displayed: no
    type: string
    allowed_values:
    - value1
    - value2
    required: yes
    masked: no

  - name: multi_choice_param
    displayed: false
    type: array
    required: true
    masked: false
    allowed_values:
    - val1
    - val2

  - name: checkbox_param
    displayed: false
    type: boolean
    required: true
    masked: false

  - name: editbox_param
    displayed: false
    type: string
    required: true
    masked: false

inputView.ejs:

<div>
  Generate an app skeleton in
  <select name="code_language" id="code_language">
    <% for(var i=0; i < languages.length; i++) { %>
    <option value="<%= languages[i] %>"><%= languages[i] %></option>
    <% }; %>
  </select>
  </select></div>
</br>
And just some additional test parameters.</br>
Multiple choice control</br>
<select name="multi_choice_param" id="multi_choice_param" multiple>
  <option value="volvo">Volvo</option>
  <option value="saab">Saab</option>
  <option value="opel">Opel</option>
  <option value="audi">Audi</option>
</select></br>
Check box</br>
<input type="checkbox" id="checkbox_param"></br>
Edit Box: <input id="editbox_param"></br>
</div>

prompt.mustache:

Generate an app skeleton in {{{code_language}}} programming language. Testing parameters of different types: {{{multi_choice_param}}}; {{{checkbox_param}}}; {{{editbox_param}}}

task.robot:

*** Settings ***
Library    OperatingSystem
Library    okailibrary
Suite Teardown    Terminate All Processes    kill=True


*** Tasks ***
Create Output
   ${output_content}=    Set Variable    {"Generated Content":"<h1>Hello World!!!</h1>"}
   Create File    output.json    content=${output_content}    overwrite=${True}

Workflow.yml¶

Every task must have a file workflow.yml maintained at the top level of its repository.

Many workflows/tasks will have parameters and some of them might be mandatory and yet cannot have any default values meaning they must be provided to such workflow at its startup time.

Use cases when workflow paramaters have to be populated: 1. When a user creates a new workspace. At this point, the user might want to schedule certain workflows to be executed at the workspace startup time. 1. When a user executes/schedules a workflow via the WSP UI toolbar.

1. Format¶

The file must be in the following format:

info:
    name: <workflow-title>
    id: com.companyname.name
    version: <x.x.x-version>
    type: task | app
    target: workspace
    workspace:
    - name: <name of a workspace where the workflow can run>:
      version: <x.x.x>
    - name: wsp2
      version: <x.x.x>
    ...

    dependencies:
    - name: <dep1-name>:
      version: <x.x.x>
      type: pip| pip3 | apt | npm
      source: https://package_repo_url | ok/<lib_id>
      packages:
      - name: <package1>
        version: <x.x.x>
        type: pip| pip3 | apt | npm
      - name: <package2>
        version: <x.x.x>
        type: pip| pip3 | apt | npm

    parameters:
    - name: token # Reserved parameter that indicates if the workflow needs to use a token
      displayed: no
      allowed_values:
      - ok_bearer_token # to access Office Kube services
      - ok_access_token # to access Office Kube repos
      actual_values:
      - ok_bearer_token
    - name: <variable1-name>
      description: <Description shown as a parameter label in the Task Management dialog, tab Parameters>
      usage: <Instructions shown as context help in the Task Management dialog, tab Parameters>. Mandatory parameter
      displayed: yes | no (default: yes) # Indicates if the paramter is displayed to the user the Task Management dialog, tab Parameters
      type: string | number | boolean | array (mandatory attribute, default: string)
      format: <display format of the value> # see https://ej2.syncfusion.com/react/documentation/maskedtextbox/mask-configuration/
      default: <default-value>
      required: yes | no (default: no)
      allowed_values: <a list of allowed values>
      masked: yes | no (default: no) # yes indicates that the parameter should be displayed as masked in the Task Management dialog, tab Parameters
      actual_values: Single value or an array values. Mandatory parameter.
      tg_target: Mandatory attribute. Acceptable values: cli, tempalte, workflow, default: workflow
    - name: <variable2-name>
    ...

1.1. Section Info¶

The attribute info->name must match the value of the workflow’s project name and some of the attributes defined in that file must be added to the list workflow’s project topics. Namely, they are type, target, workspace.

The attribute type is mandatory and indicates the (as the name implies) the type of the task. Currently, there are 2 types supported: task and app. The former indicates an automation task whereas the latter means that the task is executed by an app. The app type tasks are normally associated with a specific app. For more details refer to the section Application.

Another mandatory attribute target defines where exactly the task will be executed. The only supported value at the moment is workspace.

The attribute workspace is optional and describes which workspaces the task supports. If the workflow.yml does not define this attribute that it is assumed that the task can be executed on any workspace.

1.2. Section Dependencies¶

As the name implies, the section lists all dependencies that the workflow needs in order to properly function. For example, if a workflow needs to use a template library along with mustache, this section should include that dependency as follows:

- name: okgenerator
version: 0.1.0
source: ok/25
generators:
- mustache
type: pip3
packages:
- name: chevron
  type: pip3
  version: 0.14.0
- name: expect
  type: apt
- name: yo
  version: 4.3.0
  type: npm
- name: generator-jhipster
  version: 7.9.3
  type: npm

At minimum, each dependency must specify 3 attributes: name, version, and type.

An attribute type can have one of the following values: pip3, pip,apt, or npm. Its value instructs the workspace engine which package manager to use in order to install the dependency.

If the dependency is not available in public/default repos an optional attribute source can be used to indicate a url for the specific repo. Currently, this attribute is supported for pip3/pip only. It also should be noted that if any of the platform’s libraries is used as the dependency the format of this attribute should has the following structure: ok/<lib_id>. Here, the lib_id is an id assigned to the libray. The list of different platform libraries can be found in section Office Kube Task Libraries.

An attribute generators is specific to our template generator library.

If the dependency in turn relies on a number of packages they all should be included in the attribute packages. The attribute is a list of triples (name, type, version) similar to the atributes of the dependency itself.

1.3 Section Parameters¶

The section defines a number of paramaters that a task needs and their attributes. For the purpose of each paramater attribute refer to the section Format above. Below are some specific use cases of how to define and use parameters.

1.3.1 Authentication¶

If a task needs to use certain Office Kube resources such as services or git repositories that task’s file workfow.yml should include a special purpose parameter token and in its attribute actual_values include values ok_bearer_token and/or ok_access_token.

In this case the Office Kube workflow system will create an environment variable %{username} and variables %(ok_bearer_token} and/or %{ok_access_token) holding proper values of the tokens of the authenticated user accordingly. These values then can be used inside the task.

Here is an example of this parameter indicating to populate both types of Office Kube tokens:

parameters:
- name: token # Reserved parameter that indicates if the workflow needs to use a token
  displayed: no
  allowed_values:
  - ok_bearer_token
  - ok_access_token
  actual_values:
  - ok_bearer_token
  - ok_access_token

Then, a task that, for example, needs to clone an Office Kube repo would use the bearer token as follows:

*** Settings ***
Library       Process
*** Variables ***
${git_repo_url} https://officekube.io/somerepo.git
*** Tasks ***
Clone Repo
  Run Process git clone https://%{username}:%{ok_access_token}@${git_repo_url}

1.3.2 User-Populated Parameters¶

For a task that depends on a user’s input the section parameters can include parameters of different types and allowing different options to populate them. The following example some of these options:

parameters:
- name: text_param1
  displayed: yes
  type: string
  allowed_values:
  default: value1
  description: Mandatory Free Text Parameter
  usage: Please enter some value.
  required: yes

- name: masked_param2
  displayed: yes
  masked: yes
  type: string
  allowed_values:
  default: value3
  description: Masked Text Parameter
  usage: Please enter some value.

- name: phone_param3
  displayed: yes
  format: "000-000-0000"
  type: string
  allowed_values:
  default: 123-456-7890
  description: Phone Number
  usage: Please enter your phone number.

- name: single_choice_param4
  displayed: yes
  type: string
  allowed_values:
  - value1
  - value2
  - value3
  default: value2
  description: Single Choice Parameter
  usage: Please select a proper value.

- name: multiple_choice_param5
  displayed: yes
  type: array
  allowed_values:
  - value1
  - value2
  - value3
  default: value2
  description: Multiple Choice Parameter
  usage: Please select all that applies.

- name: checkbox_param6
  displayed: yes
  type: boolean
  default: no
  description: Checkbox Parameter
  usage: Please check mark the parameter.

3.3.3 Parameter Validation¶

There are a number of validation rules that certain parameter attributes must comply with. They are listed in the table below.

Attribute	Description
type	A mandatory attribute. Possible values: string, array, number, boolean.
tg_target	A mandatory attribute. Possible values: cli, template, workflow.
usage	A mandatory attribute. Can be any value
actual_values	A mandatory array attribute. At minimum, should have at least one non-empty value. When workflow.yml is submitted via the Workspace UI this attribute is properly populated.
allowed_values & default	When the attribute ‘type’ is “array” the attribute ‘allowed_values’ must have at least one value and if the value of the attribute ‘default’ is defined it must match at least one allowed value. The reason for this requirement is that this combination represents a multiple choice attribute which must have a default value set up.
allowed_values & default	When the attribute ‘type’ is “string” and the attribute ‘allowed_values’ has at least one value in it and if the value of the attribute ‘default’ is defined it must match at least one allowed value. The reason for this requirement is that this combination represents a single choice attribute which must have a default value set up.
tg_target & description	When the attribute ‘tg_target’ is set to “cli”, the attribute ‘description’ must be present (it can be empty). The reason for this requirement is specific to a case of so-called template libraries (see below). Command-line options for certain generators might be in the format “option value” (with any value in between, e.g. = or :). In this case the ‘description’ attribute should include the name of the option along with a suffix (e.g. –option=).

2. Use of Template Generators¶

One of the Office Kube features allows a user to generate artifacts of different kinds. Examples include software project scaffoldings, code snippets, office documents (documents, spreadsheets). This can be accomplished with the help of a Template Engine Library. The library is intended for use in a task.

2.1. Generator Dependency¶

A task developer can leverage 4 generators supported by the library. The developer is expected to indicate which generator their task will use in the section dependencies. Currently, supported generators and versions are included below.

Generate with mustache. The following dependency must be included in workflow.yml:

- name: okgenerator
  version: 0.1.0
  source: ok/25
  generators:
  - mustache
  type: pip3
  packages:
  - name: chevron
    type: pip3
    version: 0.14.0
  - name: expect
    type: apt
  - name: yo
    version: 4.3.0
    type: npm
  - name: generator-jhipster
    version: 7.9.3
    type: npm

Generate with yeoman. The library supports a number of yeoman generators listed in the table below. Workflow.yml should include each such generator that needs to be used in the task.

Generator	Version
jhipster	7.9.3
office

Jhipster dependency

name: okgenerator version: 0.1.0 source: ok/25 generators: - jhipster type: pip3 packages: - name: chevron

type: pip3 version: 0.14.0

name: expect type: apt

name: yo version: 4.3.0 type: npm

name: generator-jhipster version: 7.9.3 type: npm

Generate with CookieCutter.

Depenency for the CookieCutter

name: okgenerator version: 0.1.0 source: ok/25 generators: - cookiecutter-django type: pip3 packages: - name: chevron

type: pip3 version: 0.14.0

name: expect type: apt

name: yo version: 4.3.0 type: npm

name: generator-jhipster version: 7.9.3 type: npm

Generate with OpenAPI Generator.

Depenency for the OpenAPI Generator

name: okgenerator version: 0.1.0 source: ok/25 generators: - openapi type: pip3

2.2. Parameter Handling¶

Each generator and/or a template (used by the generator) in turn might have certain mandatory parameters that must be provided by the task that uses it. Specifically,

User populated parameters. As much as possible, generator task parameters should be populated by the task and/or the library. Ideally, a user should not be expected to populate any parameters. Parameters that can be populated by the task must have the attribute “displayed” set to “no” and the attribute “actual_values” to a proper value accordingly. This will let the Workspace UI hide such parameters from the user and yet provide the necessary values to the Workspace Engine for proper task execution.
Template Parameters. The attribute “name” of each such parameter must match a corresponding template parameter. After the workspace engine has cloned a task repo into a folder /home/me/robots/<task_name> the template engine library should grab the workflow.yml file and, depending on the generator and the attribute tg_target, dump all attributes with tg_target equal to “template” into the file parameters.exp (for interactive prompt) or cookiecutter.json or data dictionary object (for mustache) and pass all attributes with tg_target equal to “cli” to the generator.
Generator Paramaters. The table below lists all mandatory parameters for each generator and their default values assumed by the template generator library:

Generator	Paramater	Default Value
OpenAPI	ok_spec_file_path	As much as possible, the task developer should use the workspace default value (e.g. /home/me/project/api for the go workspace) and set it as “cli” non-displayable parameter in workflow.yml. The default for the library should be /home/me/robots/<task_name>/inputs/openapi.yml.
OpenAPI	ok_language	It should be populated in workflow.yml as “cli” non-displayable paramater in workflow.yml. No default value is defined in the library.
CookieCutter	ok_git_url	The parameter should be made as a “cli” non-displayble parameter. No default value for the library.
Mustache	ok_partials_path	The parameter should be made as a “cli” non-displayble parameter. Its value should be a RELATIVE path and is used by the library to determine location of mustache partials. Default value is ‘.’.
Mustache	ok_partials_ext	The parameter should be made as a “cli” non-displayble parameter. Its value should be a RELATIVE path and is used to determine an extension of files that contain mustache partials. Default value is ‘mustache’.
All	ok_inputs_path	The parameter should be made as a “workflow” non-displayble parameter. Its value should be a RELATIVE path. The default value for the library is inputs.
All	ok_outputs_path	The parameter should be made as a “workflow” non-displayble parameter. Its value should be a RELATIVE path. The default value is outputs.
All	token	The parameter should be made as a “workflow” non-displayble parameter. Its value should be a list of token the task might need. Currently, supported values are ok_bearer_token (to access services provided by Office Kube), ok_access_token (to access workflows/repos in Office Kube), github (for users that have registered with Office Kube using their github account).

Office Kube Task Libraries¶

The Office Kube platform comes with a number of libraries that can be used to facilitate development of automation tasks.

As more libraries get developed this section will be expanded. So, please be sure to check it on a regular basis.

1. Template Engine¶

The Template Engine library is an extension to the Robot Framework that facilitates generation artifacts of different types.

The library integrates the following generators:

OpenAPI Generator
CookieCutter Generator
Mustache Template engine
Yeoman Generator

Dependencies¶

The library has a number of dependencies. The most critical one is a presence of a task file workflow.yml.

The library loads and parses through the file to perform a number steps:

As noted in 2. Use of Template Generators, it checks if the section Dependencies includes proper references to a generator and its version.
It looks if the workflow.yml includes parameters ok_inputs_path and ok_outputs_path and uses their values to override default ones (inputs and outputs accordingly). These parameters if specified in the workflow.yml must have an attribute tg_target set to cli.
For specific types of generators (described below) the library also checks for presence of certain generator parameters.

Generation with Mustache¶

The library has a keyword “Generate with mustache” that can be used to generate artifacts out of provided mustache templates.

When the keyword is executed it:

Checks if the inputs folder includes at least one mustache template - a file with an extensions .mustache. If there are no templates the keyword returns an error.
Every parameter with an attribute tg_target set to template the keyword treats as a template variable with the name of the paramater attribute name and the value taken from an attribute actual_values[0].
Checks if the workflow.yml file includes a parameter ok_partials_path that includes a relative path for partials and uses its value to locate the partials that the templates might use.
Saves the generated artifacts into the outputs folder.

Here is an example of a task, workflow.yml, a mustache template using the keyword:

workflow.yml::

dependencies: - name: okgenerator

version: 0.1.0 source: ok/25 generators: - mustache type: pip3 packages: - name: chevron

type: pip3 version: 0.14.0

name: expect type: apt

name: yo version: 4.3.0 type: npm

name: generator-jhipster version: 7.9.3 type: npm

parameters: - name: ok_inputs_path

displayed: no default: description: usage: type: string required: yes masked: no actual_values: - inputs tg_target: workflow

name: ok_outputs_path displayed: no default: description: usage: type: string required: yes masked: no actual_values: - generated_code tg_target: workflow
name: sample_template_var1 displayed: no default: sample_var_1 description: Sample Variable 1 Definition usage: The variable name should include letters, numbers, and underscore only type: string required: yes masked: no actual_values: - sample_var_1 tg_target: template

task.robot:

*** Settings ***
Library       okgenerator.TemplateEngine

*** Tasks ***
Task Scaffolding Generator
  Generate with mustache

inputs/myfirsttemplate.mustache:

Here is a value of a template variable: {{{sample_template_var1}}}

Generation with Yeoman¶

The library has a keyword “Generate with yeoman” that can be used to generate artifacts with the help of a yeoman generator.

Currently, the following yeoman generators are supported:

- JHipster, version 7.9.3
- Office

When the keyword is executed it:

Every parameter with an attribute tg_target set to template the keyword treats as a template variable with the name of the paramater attribute name and the value taken from an attribute actual_values[0].
Saves the generated artifacts into the outputs folder.

Here is an example of a task and a workflow.yml using the keyword:

workflow.yml:

dependencies:
- name: okgenerator
  version: 0.1.0
  source: ok/25
  generators:
  - jhipster
  type: pip3
  packages:
  - name: chevron
    type: pip3
    version: 0.14.0
  - name: expect
    type: apt
  - name: yo
    version: 4.3.0
    type: npm
  - name: generator-jhipster
    version: 7.9.3
    type: npm

task.robot:

*** Settings ***
Library       okgenerator.TemplateEngine

*** Tasks ***
Task Scaffolding Generator
  Generate with yeoman

Generation with CookieCutter¶

The library has a keyword “Generate with cookiecutter” that can be used to generate artifacts with the help of a cookiecutter generator. The only difference in behavior between generate with yeoman and cookiecutter

Currently, the following yeoman generators are supported:

- cookiecutter-django

When the keyword is executed it:

Every parameter with an attribute tg_target set to template the keyword treats as a template variable with the name of the paramater attribute name and the value taken from an attribute actual_values[0].
Saves the generated artifacts into the outputs folder.

Here is an example of a task and a workflow.yml using the keyword:

workflow.yml:

dependencies:
- name: okgenerator
  version: 0.1.0
  source: ok/25
  generators:
  - cookiecutter-django
  type: pip3
  packages:
  - name: chevron
    type: pip3
    version: 0.14.0
  - name: expect
    type: apt
  - name: yo
    version: 4.3.0
    type: npm
  - name: generator-jhipster
    version: 7.9.3
    type: npm


parameters:
- name: project_name
  displayed: yes
  default: project
  description:
  usage: project_name
  type: string
  required: yes
  masked: no
  actual_values:
  - project
  tg_target: template

- name: project_slug
  displayed: yes
  default: project
  description:
  usage: project_slug
  type: string
  required: yes
  masked: no
  actual_values:
  - project
  tg_target: template

- name: description
  displayed: yes
  default: created with officekube
  description: Describe the website
  usage: description
  type: string
  required: yes
  masked: no
  actual_values:
  - created with officekube
  tg_target: template

- name: author_name
  displayed: yes
  default: officekube
  description: author_name
  usage: author_name
  type: string
  required: yes
  masked: no
  actual_values:
  - officekube
  tg_target: template

...

- name: debug
  displayed: no
  default: n
  description:
  usage: debug
  type: string
  required: yes
  masked: no
  allowed_values:
    - y
    - n
  actual_values:
    - n
  tg_target: template

task.robot:

*** Settings ***
Library       okgenerator.TemplateEngine

*** Tasks ***
Task Scaffolding Generator
  Generate with cookiecutter

Generation with OpenAPI¶

The library has a keyword “Generate with openapi” that can be used to generate artifacts with the help of openapi generator.

The generator expects an openapi specification file either in json or yaml format. The generator currently supports both OAS 2.0 and OAS 3.0.

Currently, the generator can generate artifacts in the following languages:

Java

Go

Node

Python

When the keyword is executed it:

Checks if the inputs folder contains a file with openapi.json or openapi.yml with a valid OAS specification
Every parameter with an attribute tg_target set to template the keyword treats as a template variable with the name of the paramater attribute name and the value taken from an attribute actual_values[0].
Saves the generated artifacts into the specified outputs folder

Here is an example of a task and workflow.yml using the keyword:

workflow.yml:

dependencies:
- name: okgenerator
  version: 0.1.0
  source: ok/25
  generators:
  - openapi
  type: pip3
  packages:
  - name: chevron
    type: pip3
    version: 0.14.0
  - name: expect
    type: apt
  - name: yo
    version: 4.3.0
    type: npm
  - name: generator-jhipster
    version: 7.9.3
    type: npm

  parameters:
    - name: language
      displayed: yes
      default: java
      description: Programming language to be used to generate the code
      usage:
      type: string
      required: yes
      masked: no
      actual_values:
        - java
      allowed_values:
        - java
        - go
        - node
        - python
      tg_target: cli

    - name: app_name
      displayed: yes
      default:
      description:
      usage: The base name of the application
      type: string
      required: yes
      masked: no
      actual_values:
        - generatedService
      tg_target: workflow

    - name: ok_inputs_path
      displayed: no
      default:
      description:
      usage:
      type: string
      required: yes
      masked: no
      actual_values:
        - inputs
      tg_target: workflow

    - name: ok_outputs_path
      displayed: no
      default:
      description:
      usage:
      type: string
      required: yes
      masked: no
      actual_values:
        - generated_code
      tg_target: workflow

task.robot:

*** Settings ***
Library okgenerator.TemplateEngine

*** Tasks ***
Task Scaffolding Generator
  Generate with openapi

2. AI Library¶

The AI library is an extension to the Robot Framework that facilitates interaction with the platform AI capabilities. The following is an example of using the library in a workflow to generate documentation for source code.

workflow.yml:

dependencies: - name: okailibrary

version: 0.1.0 source: ok/115 type: pip3

parameters:

name: source_dir displayed: yes default: /work/project description: Source Code Folder usage: Enter a full path (in your workspace) where your source code resides. type: string required: yes masked: no actual_values: - /work/project
name: doc_dir displayed: yes default: /work/project/docs description: Documentation Folder usage: Enter a full path (in your workspace) where documentation files should be stored. type: string required: yes masked: no actual_values: - /work/project/docs
name: code_language displayed: yes default: description: Programming Language usage: Select Programming Language type: array required: yes masked: no allowed_values: - c - cpp - go - html - java - js - markdown - php - proto - python - rst - ruby - rust - scala - sol - swift - vb6
name: token type: string tg_target: workflow usage: The parameter includes a list of tokens that the task needs. allowed_values: - ok_bearer_token displayed: no default: ok_bearer_token actual_values: - ok_bearer_token

task.robot:

*** Settings ***

Library okailibrary.DocGenerator Suite Teardown Terminate All Processes kill=True

* Variables * ${source_dir} /work/aigen_test ${code_language} go ${doc_dir} /work/aigen_test/docs

* Tasks * Generate Docs

${result}= Generate Source Code Docs ${source_dir} ${doc_dir} ${code_language} ${json}= evaluate json.loads(‘’’${result}’’’) json Log ${json[“Code”]}

Applications¶

An application (or an app) is a piece of code that executes on a workspace. The app can have a CLI and/or a web-interface.

As mentioned earlier, there are apps included in every workspace. These are Terminal, File Browser, Midnight Commander, and htop (process viewer).

Additional apps can be installed using the workspace toolbar menu Apps.

It should be noted that while there are no enforced constraints on how many apps can be installed and run (concurrently) on a workspace, a user should take into consideration limitations of their workspace defined by the amount of compute resources (CPU/Memory) available on the workspace.

Why to use Apps¶

There are several use cases where you can consider using an app. Examplses include (but are not limited to):

Use of the app as in case of a desktop app: a user starts the app from the toolbar or from the terminal.
Use of the app as a part of a workflow: in this scenario the app is used at one or more steps of a workflow that can be triggered manually (from the task menu) and/or automatically.
Use of a SaaS app. This case covers a scenario where the user utilizes a third-party app that is hosted as SaaS. For instance, one can import data from their google spreadsheet in order to process and use its data within a workflow.

As with workflows, we constantly improve and grow a repository of available apps. Please check in to see for more apps and/or contact us if you would like a certain app to become available in our repo.

Documentation

Documentation

Table Of Contents

Welcome to Office Kube Documentation!¶

Overview¶

1. Workspace¶

Applications¶

User Interface¶

Project Repository¶

Authentication¶

Workflow Engine¶

Some Workspace Mechanics¶

2. Workflows¶

3. Apps¶

4. Tool Workspaces¶

Developer Workspaces¶

Artifact Generation¶

Task Developer Guide¶

1. Create¶

2. Build¶

Libraries¶

Task Input Parameters¶

3. Test¶

Execution¶

Viewing Results¶

Debugging¶

Environment Variables¶

4. Publish¶

Prompt Task¶

Workflow.yml¶

1. Format¶

1.1. Section Info¶

1.2. Section Dependencies¶

1.3 Section Parameters¶

1.3.1 Authentication¶

1.3.2 User-Populated Parameters¶

3.3.3 Parameter Validation¶

2. Use of Template Generators¶

2.1. Generator Dependency¶

2.2. Parameter Handling¶

Office Kube Task Libraries¶

1. Template Engine¶

Dependencies¶

Generation with Mustache¶

Generation with Yeoman¶

Generation with CookieCutter¶

Generation with OpenAPI¶

2. AI Library¶

Applications¶

Why to use Apps¶