Template File Format

Toolchain YML

The format of the toolchain template file is described in detail in this document.

Toolchain format

version: '2'
messages:
  $i18n:

template:
  name: 
  description:
  header:
  icon:
  required:
  info:

toolchain:
  name:
  description:
  organization_guid:
  generator:
  template:
  key:

services:
  name:
  service:

form:
  service_id:
    schema:
      $ref:
    parameters:

Toolchain format, section by section

Use the following reference material to understand the content of each section of the toolchain file. You can find examples and learn what is required or optional.

Top level sections

version: '2' => required

messages:

template => required

toolchain:
  
services:
  
form:

The top level of the template specifies the current template version (required), the Messages Section, the Template Section (required), the Toolchain Section, the Services Section and the Form Section.

Version

version: '2'

(required, string)

The current version of the template format. This value is constant and not cannot be modified by the users of the toolchain teamplate.

---

Messages Ssection

The messages section is an optional section that defines a way to import the template strings and their translations required. It contains the special i18n ref that resolves to the keys and their strings in a client's preferred locale.

The following example shows an $i18n reference to a locales.yml file:

messages: 
  $i18n: locales.yml

The locales.yml file would then import the messages for each supported locale. Here is an example locales.yml file.

Finally, the template engine would replace i18n with only the strings for a client's preferred locale. If the engine is not able to satisfy the client's preferred locale, then it would use the strings of the default locale (that is, root) given in locales.yml. The following example shows the messages object ultimately resolved for a fr (French) locale.

"messages": {
   "template.name": "Chaîne d'outils Cloud Foundry simple",
   "template.description": "Cette chaîne d'outils vous permet de développer et de déployer une application Cloud Foundry.",
   "deploy.title": "Etape de déploiement exemple",
   "deploy.description": "Chaîne d'outils exemple",
   "deploy.longDescription": "Delivery Pipeline automatise le déploiement en continu.",
   "deploy.appDescription": "Nom de votre appli Hello World",
   "deploy.appName": "Nom de l'application",
   "region": "Région"
}

The messages file(s) that get imported by the locales.yml file can contain strings that can be used in three places:

• Template strings
• UI strings
• SVG image strings

This messages.yml file is an example of a message file that contains all three types of strings.

Template strings are JSON ref substitutions for the values in the template such as name or description. In the following example, the name and description are local JSON references to the keys template.name and template.description of the messages object, respectively:

name:
  $ref: "#/messages/template.name"
description:
  $ref: "#/messages/template.description"

If no localization is needed:

name: "Simple Cloud Foundry Toolchain"
description: "sample toolchain"

UI strings are used to translate custom UI elements. See the Form section for more information on how to localize a custom UI.

SVG strings are used to externalize the text in SVG images. This is done by assigning an ID (matching with one of the keys in messages) to the text that you want translated. For example here we assign the ID "issueTracker" :

<text id="issueTracker" transform="matrix(0.9271 0 0 1 1.9888 130.2944)" class="st26 st27">ISSUE TRACKER</text>

Messages section properties

messages:

(optional, $i18n)

An $i18n ref to the yml file location that contains the English strings as well as their translations.

---

Template section

The template section contains metadata about the template, and it is the other element that is required in order to render a template, in additional to the version parameter.

You don't need to write very much in order to produce a valid template. Here, for example, is the world's smallest (valid) toolchain template:

---
version: '2'
template:
  

This template, of course, doesn't do very much, but it will still render.

Here are the other properties that can be added to make the template more useful.

Template section properties

name:

(optional, string)

The name of the template. Will be displayed to the user near the top of the setup page.

name: "Simple Cloud Foundry Toolchain"

description:

(optional, string in Markdown format)

The description of the template. The description text is displayed to the user in the sidebar on the setup page. Conventionally, the description should tell the user what the template is for, explain what services the template adds to created toolchains, and offer links to more detailed documentation.

header:

(optional, string in Markdown format)

The header property will be displayed to the user in the setup page's main content area. While the header property can contain any markdown text, it conventionally contains just a single image tag. For example, the following is a typical header:

header: '![Image showing preview of the toolchain](toolchain.svg)'

Breaking down the parts of the header shown above:

• Image showing preview of the toolchain: Gives the alt text for the image tag.
• toolchain.svg: Gives the path to the header image file. In this case, toolchain.svg is an SVG image located in the same folder as the template's toolchain.yml file.

Note that the setup page applies special styling to the first image (if any) present in the header field, by resizing it to be consistent with the page layout.

Localizing the header image

The template can indicate that an SVG header image should be localized. To enable a header image for localization, append ?localize to the header image's file path. For example, the following header will trigger localization of toolchain.svg:

header: '![](toolchain.svg?localize)'

Localization is performed using the mechanism described in the Messages Section. Localization is supported only for SVG format images.

icon:

(optional, string)

A reference to an icon that is displayed at the top of the page next to the template name.

required:

(optional, array of string)

A list of keys from the services map that must be completed before the toolchain creation. Each service in the list will be identified by an asterisk (*) in the UI to indicate that it should be completed. The user must fill out the service's section in the UI before the toolchain creation can continue.

In this example we are requiring the completion of the 'my-delivery-pipeline' and 'my-repo' sections.

name: "Simple Cloud Foundry toolchain"
required: 
 - my-delivery-pipeline
 - my-repo

info:

(optional, object)

Gives the repo url and the repo branch where the template is hosted. This information is displayed in the sidebar on the setup page.

info:
    git url: [https://github.com/open-toolchain/simple-toolchain](https://github.com/open-toolchain/simple-toolchain)
    git branch: [master](https://github.com/open-toolchain/simple-toolchain/tree/master)

---

Toolchain section

The toolchain section is an optional section that contains information about the toolchain to be created.

Toolchain section properties

key:

(optional, string)

Unique identifier for the toolchain.

name:

(optional, string)

A name for the yet-to-be created toolchain.

organization_guid:

(optional, string)

Globally unique identify (GUID) of the organization that this toolchain will be created in.

description:

(optional, string)

A description for this toolchain.

Internal properties

The following properties are not really of interest to template authors, but they are included for completeness:

generator:

(optional, string)

Metadata field about who is creating this toolchain.

template:

(optional, object)

Metadata about the template that created this toolchain. It can contain the string or ref to getting_started text that will be displayed to the user after the toolchain is created. The following example shows its usage:

template:
    getting_started: "Getting Started Text"

---

Services section

The services section is where you define the services that are to be used in your toolchain. While the format of each service definition is generally the same, you need to consult the service's schema to determine what parameters the service requires.

Here is the complete list of services you can currently include in your templates.

Services section properties

The common part shared by all services includes the following fields:

name

(optional, string)

A user-generated string used to identify this service in the context of the current file. This name can be used to mark a service as required.

service_id

(optional, string)

A unique string that identifies the service. This string comes directly from the service catalog. Consult the service catalog to find the appropriate ID.

parameters

(optional, string)

One or more configuration parameters for the service. These vary between services: users need to consult the catalog in order to figure out what parameters a particular service requires. Consult the service catalog to find the appropriate parameters for a service.

services:
  sample-repo:
      service_id: githubpublic
      parameters:
        repo_name: "sample-{{name}}"
    repo_url: https://github.com/open-toolchain/node-hello-world
        type: clone
        has_issues: true

Internal properties

The following property is not of interest to template authors, but it is included for completeness:

schema

(optional, JSON Schema object)

If provided, overrides the schema specified by the broker's catalog entry. Note that using a schema that differs from the catalog entry can lead to configuration errors from the broker.

---

Form section

All services that require parameters will have a default UI provided by the setup page. Services can also specify a custom UI by providing a forms element in their declaration.

Individual templates can override any UI provided by a service by specifying the new UI in a new section. This section needs to contain these form properties:

Form section properties

service_id

(string)

The service_id of the service whose UI you are overwriting. In the example provided below, note that you just use the service_id as a name parameter ("pipeline").

schema

($ref to a Custom UI file)

Refers to a JSON file that provides the custom UI for this service. See Template Custom UI for a complete explanation of the format.

parameters

(string)

Initial values for properties that are used by the custom UI you are defining.

form:
  pipeline:
      schema: 
        $ref: deploy.json
      parameters:
        prod-region: "{{region}}"
        prod-organization: "{{organization}}"
        prod-space: "{{space}}"
        prod-app-name: "{{sample-repo.parameters.repo_name}}"

For more information about how to extend the UI, see the Custom UI Example.