How to Create a Template

Before You Start

Before you start, make sure you've done the following:

• Installed the latest version of Doohickey CLI
• Initialized an integration project.
  • See Setup a New Project
• Installed the Doohickey Types NPM package within your project directory
  • If you generated your project with doohickey init, this step has already been completed for you.

Step-by-Step Guide

Step 1: Run Doohickey Template command

First, determine if you are trying to generate a scheduled or a webhook triggered template.

• Scheduled templates, which become scheduled flow instances, are triggered on a cron schedule
• Webhook triggered templates, which become webhook triggered flow instances, are triggered by an HTTP request to a webhook endpoint

To generate a base template file, run the command doohickey template create TEMPLATE_ALIAS, replacing TEMPLATE_ALIAS with the alias you would like to give this template, ex. order_placed, product_return, etc.

If you are generating a scheduled template, pass the flag -S XXXXX replacing XXXXX with the cron expression you would like the schedule to run on. For example, the expression * * * * * will run every 60 seconds. If you are generating a webhook template, simply exclude this flag.

For the purposes of this example, we will create a webhook triggered template. Prior to running this command, ensure you are located in your integration project directory.

doohickey template create TEMPLATE_ALIAS

Step 2: Locate Created Template

After running the template create command, your template should now be located in your current directory, under the templates folder. You should see a folder created with the alias name you used to create the template. Within that folder will be a JavaScript file containing your template.

For example, if you created a product_return template in the my_integration folder, your directory should look similar to this:

my_integration /
  templates /
    product_return /
      product_return.js

Step 3: Review Template Contents

Once you have located and opened your template, take note of a few key elements.

Template Parameters

You'll notice there are a few parameters that are passed into the template function.

Name

The name parameter references:

• The value of the flow name passed into the template when deploying locally
• The value of the template's name from the template endpoint when deploying from Doohickey Cloud

To learn more about the Doohickey Cloud Template, review the documentation here.

Description

The description parameter references:

• The value of the flow description passed into the template when deploying locally
• The value of the template's description from the template endpoint when deploying from Doohickey Cloud

To learn more about the Doohickey Cloud Template, review the documentation here.

Components

The components parameter is an object containing all aliased components in the corresponding OIH environment.

For example, if you have a component aliased as rest, you can access that component's ID and pass it into a component step by referencing components.rest

{
  rest: "123456",
  jsonata: "654321"
}

Tenant

The tenant parameter is an object containing the corresponding OIH tenant. The tenant ID is accessible by referencing tenant.id

{
  id: "123456789"
}

Config

The config parameter is an object that represents:

• An Integration Config when deployed to Doohickey Cloud
• A custom configuration object when deployed in a local environment

When deploying your flow in a local development environment, you can pass a file path to a configuration JSON that allows you to mock a Doohickey Cloud Integration Config object. Here is an example configuration JSON.

{
  "warehouseCode": "76007",
  "customerNumber": "ABC621",
  "secrets": {
    "ecommerce-store": "ecommerce-store-for-testing-locally"
    // Doohickey Cloud Secret Alias || Local Doohickey CLI Secret Alias
  }
}

The secrets property in your local configuration object allows you to map your local OIH secret aliases to the secret alias that will ultimately be in the Doohickey Cloud Integration Config object.

OIHFlow

In the auto generated template, a base Open Integration Hub (OIH) template has already been started.

    const myFlow = OIHFlow;
    myFlow.name = name || 'Name of Flow';
    myFlow.description = description || 'Optional description.';
    myFlow.tenant = tenant.id;

Component Steps

In the auto generated template, there are three components automatically created for you.

• A Webhook component that exists to retrieve messages from a webhook

    const webhookStep = WebhookComponent.receive({
      name: "Example Step",
        id: "example-step",
        componentId: components.webhook,
        fields: {
          auth: false
        }
    });
    myFlow.graph.nodes.push(webhookStep);

• A JSONata component that exists to apply JSONata expressions to a JSON object
  • To learn more about the JSONata query language, visit the docs here

    const transformationStep = JSONataComponent.transform({
      name: "Example Step 2",
        id: "example-step-2",
        componentId: components.jsonata,
        fields: {
          expression: require("./jsonata/sample.raw.jsonata")
        }
    })
    myFlow.graph.nodes.push(transformationStep);

Note: when working with legacy flows of type oih, the file should be included as follows:

        fields: {
            expression: DOOHICKEY.file.formatJSONata("jsonata/sample.jsonata")
        }

• A Code component that exists to execute JavaScript functions

    const codeStep = CodeComponent.execute({
        name: "Example Step 3",
        id: "example-step-3",
        componentId: components.code,
        fields: {
            code: require("./js/sample.raw.js")
        }
    })
    myFlow.graph.nodes.push(codeStep);

Note: when working with legacy flows of type oih, the file should be included as follows:

        fields: {
            expression: DOOHICKEY.file.formatJS("js/sample.js")
        }

At the bottom of each component, there is a call to myFlow.graph.nodes.push(COMPONENT_VAR). These methods attach your components to the OIH flow instance and allows them to be used as a source or a target property on the graph.

Including External Files

The template type determines how external files can be included in the template.

"oih-bundled" type

Include external files by using the built in Node.js require() function, specifying the path to the file as a string argument.

The following types of file inclusion are supported:

• JavaScript: files may be included when their file extension ends in .raw.js, e.g. require('./path/to/code.raw.js')
• JSONata: files may be included when their file extension ends in .raw.jsonata, e.g. require('./path/to/map.raw.jsonata')
• JSON: files may be included when their file extension ends in .raw.json, e.g. require('./path/to/data.raw.json')
• GraphQL: files may be included when their file extension ends in .raw.gql, e.g. require('./path/to/query.raw.gql')

Notes on including files with oih-bundled type templates:

• The file name must end in .raw.js, .raw.jsonata, .raw.json, or .raw.gql
• The file name must be a string, not a variable or constant
  • Works: require('./path/to/file.raw.js')
  • Fails: const filePath = './path/to/file.raw.js'; require(filePath);
• Included files do not have to be within the same template folder

"oih" type

Include external files by using the DOOHICKEY.file object, which contains two methods: formatJS() and formationJSONata(). Rather than having to copy your JavaScript or JSONata file and escape it manually, the DOOHICKEY.file methods will do that for you.

Notes on including files with oih type templates:

• The files and file paths provided in both the formatJS and formationJSONata methods are not generated by the template create command. You will need to do this manually if you intend to use the methods.
• The files included via the DOOHICKEY.file methods must be in the template folder, and files outside of the template folder cannot be included.

Step 4: Customize Your Template

The template that was generated is an example of a flow instance that will:

• Receive a JSON object at a webhook
• Applies a JSONata expression to the original JSON object
• Executes a function that will send the result of the JSONata transformation to a REST endpoint so we can monitor the results.

You can use this template as a base to begin to customize and build your own template.

See Also

• Templates
• Doohickey Types NPM Package
• Components