Skip to content

Getting Started - Creating Your First Refinery Project

This tutorial will walk you through how to make your first Refinery project. While the first project is a simple one it will help you better understand some of Refinery's features, as well as getting a general feel for the designer.

Creating a New Project

First thing to do is to create a new project. Navigate to the projects page, type your desired project name in the Project Name field, and click Create Project! Once you've done this you now have a blank canvas ready for your next creation.

Adding Your First Block

Let's add our first block to the new project, click the Add Block button on the left-side of the page. Select the Code Block option from the menu and a new Code Block will be added to your project. To better keep track of what is what, rename the Block Name to Hello Block (or whatever you prefer).

Then, edit the code to be the following Python code:

def main(block_input, backpack):
    print( "Hello" )
    return "World!"

Note

Refinery supports more languages than just Python! Currently support includes Go 1.12, Node 8.10, and PHP 7.3 as well. You can change the language the Code Block uses by changing the drop-down option under the Block Runtime section of the Edit Block pane.

Adding Your Second Block

What is Hello without World? Add a second block to your new project by again clicking on the Add Block button on the left-side of the page. With this Code Block set the name to World Block and the code to the following:

def main(block_input, backpack):
    print( block_input )
    return False

The above code just prints the input passed to the Code Block. We now have two Code Blocks but the magic comes in connecting blocks together in the editor.

Connecting the Blocks

Click on the Hello Block to select it and then click the Add Transition button on the left side of the page. Select the then transition from the presented menu. You will see that the World Block begins to flash indicating that you can transition to it from the currently-selected Hello Block. Click on the World Block to create the transition.

What are Transitions?

In Refinery transitions indicate the path that an execution flow will take once deployed. This means that once deployed, if the Hello Block is executed the World Block will be executed afterwards (assuming no exception occurs while running Hello Block). The data returned from the Hello Block will automatically be passed as input to the World Block (e.g. the block_input parameter in main()). Note that blocks in the Editor tab which we are currently using will not trigger other blocks until they are deployed. This allows you to modify and iterate on your Refinery Code Blocks without triggering the entire execution flow.

In our specific case, this means that the World! string returned from the Hello Block block:

# Code in Hello Code Block
def main(block_input, backpack):
    print( "Hello" )
    return "World!"

Will be passed as input to the World Block:

# Code in World Code Block
def main(block_input, backpack):
    print( block_input )
    return False

Note that even though this example uses Python for both Code Blocks, you can pass data between Code Blocks of any language type! You can return data from a Node 8.10 Code Block to a Go 1.12 Code Block and it will work the same way. This is a fairly interesting property because it means you can import Code Blocks into your project in a language you don't write and still use them for your Refinery project.

Note

It's important to note that you can only return JSON-serializable data. This means simple data types like integers, strings, arrays and simple objects are all perfectly fine to pass between Code Blocks. This restriction allows the ability to pass data between multiple languages, but does restrict what types of data can be passed around.

Scheduling a Continually-Executing Job

Let's make our project a job which will execute every minute! Click on the Add Block button again and select the Timer Block from the menu. Modify the Block Name field to be Every Minute and change the Schedule Expression to be rate(1 minutes) instead of rate(2 minutes). Finally, add a transition from the Timer Block to the Hello Block.

We've now made our project into a continually-executing job which will execute every minute once we've deployed it. Unlikely conventional server-based architecture, jobs deployed on Refinery require significantly less maintenance. You never have to perform system maintenance on the servers executing your job. Additionally you are charged purely for the compute and resources used to execute the job (instead of paying for an idling VPS or dedicated server, for example).

Deploying the Project

You can now deploy your project by clicking the Deploy Project button on the left-side of the page and confirming the action by clicking the Confirm Deploy button.

Once you've done this you've successfully deployed your first Refinery project, pat yourself on the back!

If you wait sixty seconds you will see your first scheduled job execute. This brings us to the next topic of discussion...

Deployed Project Logging & Debugging

Once you've deployed a project the Block Executions pane will automatically open. You can also manually open the panel by clicking the Block Executions button on the left side of the page.

The Block Executions panel shows a list of executions which have occurred for this deployment. These executions are grouped into "execution pipelines", which means that you can follow a chain of executions from the start to the end of the chain. This allows you to follow the flow of execution in your deployed service and better understand the chain of events that led to a particular error or bug.

Once you select a given execution pipeline from the list you'll see that the Code Blocks are marked as successful or unsuccessful . These indicate whether or not your Code Block encountered an uncaught exception or if it executed successfully without issue.

By default Refinery logs the full input data, return data, and program terminal output. This is to allow for easy reproducibility of bugs by allowing for replaying the Code Block input in the Editor tab to trigger the bug as it occurred in the deployment.

For ongoing executions the Code Blocks will automatically update as the execution continues.

If you'd like to learn more about what Refinery logs and how to better debug your deployed project, see the Debugging & Logging documentation.

Tearing Down Your Deployment

Although it has been fun, you probably don't want to run the Hello World project forever. You can tear down your deployment by clicking on the Destroy Deploy button on the left-side of the page. This will take down your deployment and bring you back to the Editor tab. You can then make changes in the Editor and deploy them all over again!

Going Forward

Now that you've deployed your first project on Refinery, why not try something a bit more complicated?