A factory configuration is a JSON snippet either stored within Che or as a .factory.json file. You can create factories within the IDE using the Che URL syntax, within the dashboard, or on the command line with the API and CLI.

factory : {
  "v"         : 4.0,            (1)
  "workspace" : {},             (2)
  "policies"  : {},             (3)
  "ide"       : {},             (4)
  "creator"   : {},             (5)
}
1 Version of the configuration format.
2 Identical to workspace:{} object for Eclipse Che.
3 (Optional) Restrictions that limit behaviors.
4 (Optional) Trigger IDE UI actions tied to workspace events.
5 (Optional) Identifying information of author.

The factory.workspace is identical to the workspace:{} object for Eclipse Che and contains the structure of the workspace. To learn more about the workspace JSON object, see Workspace Data Model.

You can export Che workspaces and then reuse the workspace definition within a factory. Che workspaces are composed of the following:

  • 0..n projects

  • 0..n environments that contain machines to run the code

  • 0..n commands to execute against the code and machines

  • a type

The factory.policies, factory.ide, and factory.creator objects are unique to factories. They provide meta information to the automation engine that alter the presentation of the factory URL or the behavior of the provisioning.

Mixins

A mixin adds additional behaviors to a project as a set of new project type attributes. Mixins are reusable across any project type. To define the mixins to add to a project, specify an array of strings, with each string containing the identifier for the mixin. For example, "mixins" : [ "pullrequest" ].

Mixin ID Description

pullrequest

Enables pull request workflow where Che handles local and remote branching, forking, and pull request issuance. Pull requests generated from within Che have another factory placed into the comments of pull requests that a PR reviewer can consume. Adds contribution panel to the IDE. If this mixin is set, it uses attribute values for project.attributes.local_branch and project.attributes.contribute_to_branch

  • The pullrequest mixin requires additional configuration from the attributes object of the project. If present, Che will use the project attributes as defined in the factory. If not provided, Che will set defaults for the attributes.

  • Learn more about other link:TODO: link to project API docs[mixins]

Pull Request mixin attributes

Project attributes alter the behavior of the IDE or workspace.

Different Eclipse Che plug-ins can add their own attributes to affect the behavior of the IDE or workspace. Attribute configuration is always optional and if not provided within a factory definition, the IDE or workspace sets it.

Attribute Description

local_branch

Used in conjunction with the pullrequest mixin. If provided, the local branch for the project is set with this value. If not provided, the local branch is set with the value of project.source.parameters.branch (the name of the branch from the remote). If both local_branch and project.source.parameters.branch are not provided, the local branch is set to the name of the checked out branch.

contribute_to_branch

Name of the branch that a pull request will be contributed to. The value of project.source.parameters.branch is default. It is the name of the branch that this project was cloned from.

Following is a snippet that demonstrates full configuration of the contribution mixin.

factory.workspace.project : {
  "mixins"     : [ "pullrequest" ],

  "attributes" : {
    "local_branch"         : [ "timing" ],
    "contribute_to_branch" : [ "master" ]
  },

  "source" : {
    "type"       : "git",
    "location"   : "https://github.com/codenvy/che.git",
    "parameters" : {
      "keepVcs" : "true"
    }
  }
}

Policies

Following is an example of a factory policy.

factory.policies : {
  "referer"   : STRING,                 (1)
  "since"     : EPOCHTIME,              (2)
  "until"     : EPOCHTIME,              (3)
  "create"    : [perClick | perUser]    (4)
}
1 Works only for clients from a referrer.
2 Factory works only after this date.
3 Factory works only before this date.
4 Create one workpace per click, user, or account.

Limitations

You can use since : EPOCHTIME, until : EPOCHTIME, and referer as a way to prevent the factory from executing under certain conditions. since and until represent a valid time window that allows the factory to activate. The referrer checks the hostname of the acceptor and only allows the factory to execute if there is a match.

Multiplicity

Using create : perClick causes every click of the factory URL to generate a new workspace, each with its own identifier, name, and resources. Using create : perUser causes only one workspace to be generated for each unique user that clicks on the factory URL. If the workspace has previously been generated, the existing workspace is reopened.

Customizing the IDE

factory.ide.{event} : {                 (1)
  "actions" : [{}]                      (2)
}

factory.ide.{event}.actions : [{
  "id"         : String,                (3)
  properties : {}                       (4)
}]
1 event = onAppLoaded, onProjectsLoaded, onAppClosed.
2 List of IDE actions to be executed when the event is triggered.
3 Action for the IDE to perform when the event is triggered.
4 Properties to customize action behavior.

You can instruct the factory to invoke a series of IDE actions based on events in the lifecycle of the workspace.

onAppLoaded

Triggered when the IDE is loaded.

onProjectsLoaded

Triggered when the workspace and all projects have been activated or imported.

onAppClosed

Triggered when the IDE is closed.

Following is an example that associates a variety of actions with all of the events.

"ide" : {
  "onProjectsLoaded" : {                                               (1)
    "actions" : [{
      "id" : "openFile",                                               (2)
      "properties" : {                                                 (3)
        "file" : "/my-project/pom.xml"
      }
    },
    {
      "id" : "runCommand",                                             (4)
      "properties" : {
        "name" : "MCI"                                                 (5)
      }
    }
  ]},
  "onAppLoaded": {
     "actions": [
        {
           "properties:{
              "greetingTitle": "Getting Started",                      (6)
              "greetingContentUrl": "http://example.com/README.html"   (7)
           },
           "id": "openWelcomePage"
        }
     ]
  },
  "onAppClosed" : {                                                    (8)
    "actions" : [{
      "id" : "warnOnClose"                                             (9)
    }]
  }
}
1 Actions triggered when a project is opened.
2 Opens a file in the editor. Can add multiple.
3 The file to be opened (include project name).
4 Launch command after the IDE opens.
5 Command name.
6 Title of a Welcome tab.
7 HTML file to be loaded into a tab.
8 Actions to be triggered when the IDE is closed.
9 Show warning when closing a browser tab.

Each event type has a set of actions that can be triggered. There is no ordering of actions executed when you provide a list; Che will asynchronously invoke multiple actions if appropriate. Some actions can be configured in how they perform and will have an associated properties : {} object.

onProjectsLoaded Event

Action Properties? Description

runCommand

Yes

Specify the name of the command to invoke after the IDE is loaded. Specify the commands in the factory.workspace.commands : [] array.

openFile

Yes

Open project files as a tab in the editor.

onAppLoaded Event

Action Properties? Description

openWelcomePage

Yes

Customize the content of the welcome panel when the workspace is loaded. Note that browsers block http resources that are loaded into https pages.

onAppClosed Event

Action Properties? Description

warnOnClose

No

Opens a warning pop-up window when the user closes the browser tab with a project that has uncommitted changes. Requires project.parameters.keepVcs to be true.

Action: Open File

This action opens a file as a tab in the editor. You can provide this action multiple times to have multiple files open. The file property is a relative reference to a file in the project source tree. The file parameter is the relative path within the workspace to the file that should be opened by the editor. The line parameter is optional and can be used to move the editor cursor to a specific line when the file is opened. Projects are located in the /projects/ directory of a workspace.

{
  "id" : "openFile",
    "properties" : {
      "file" : "/my-project/pom.xml",
      "line" : "50"
  }
}

Action: Find and Replace

In projects created from a factory, Che can find and replace values in the source code after it is imported into the project tree. This lets you parameterize your source code. Find and replace can be run as a Run Command during onProjectsLoaded event. You can use sed, awk, or any other tools that are available in your workspace environment.

To define a command for your workspace in factory.workspace.workspaceConfig.commands:

{
  "commandLine": "sed -i 's/***/userId984hfy6/g' /projects/console-java-simple/README.md",
  "name": "replace",
  "attributes": {
    "goal": "Common",
    "previewUrl": ""
  },
  "type": "custom"
}

In the preceding example, a named command replace is created. The command replaces each occurrence of * with the string userId984hfy6 in the README.md file of the project.

Then register this command to the execution list linked to the onProjectsLoaded event. In this example, the replace command is executed after the project is imported into a workspace.

"ide": {
    "onProjectsLoaded": {
      "actions": [
        {
          "properties": {
            "name": "replace"
          },
          "id": "runCommand"
        }
      ]
    }
  }

Use regular expressions in sed, both in find-replace and file-file type patterns.

Creator

This object has meta information that you can embed within the factory. These attributes do not affect the automation behavior or the behavior of the generated workspace.

factory.creator : {
  "name"      : STRING,            (1)
  "email"     : STRING,            (2)
  "created"   : EPOCHTIME,         (3)
  "userId"    : STRING             (4)
}
1 The name of the author of this configuration file.
2 The author’s email address.
3 This value is set by the system.
4 This value is set by the system.
Tags: chedir factories