Script Ninja Documentation

Getting Started

Script Ninja's Ruby environment includes Ruby Gems (library functions) for accessing commonly needed facilities like HTTP routines and persistent storage. In addition, it presents a convenient convention for returning script results to an HTTP request.

Scripts are written in Ruby version 2.6. If you are new to Ruby, we recommend first checking out "Ruby in Relatively Few Words".

Script Structure

Script Ninja Scripts are a sequence of executable Ruby statements, implicitly wrapped in a function, and ending with a return statement. There is no "main" function—execution begins with the first statement and proceeds on.

products = ShopifyAPI::Product.all
products.each do |product|
    puts product.title
end

Shopify API Version and Authentication

Script Ninja handles API Authentication for you behind the screens, with the equivalent to the following code is injected before your script:

shopify_session = ShopifyAPI::Session.new(domain: "MYSHOPIFY_DOMAIN", api_version: '2020-01', token: YOUR_TOKEN)

As you will note, the Shopify API version used is currently 2020-01.

Values Passed to the Script

Script Ninja passes parameters into your script the hash variables _params, _hook and _storage.

_params hash variable

Scripts on Script Ninja can optionally be invoked from your Shopify online store (see: Invoking Scripts from your Online Store). The URL structure for accessing such a script is: https://your-store.myshopify.com/tools/script-camp?uuid=< your script's UUID>&foo=bar. URL parameters from such requests are passed into the _params variable.

You can access the value of the foo URL parameter by calling _params["foo"] in your Script Ninja script.

_hook hash variable

The _hook hash contains the event information provided by Shopify Webhook Events. The content of the hash is dependent on the Shopify Event used to invoke the script. Please see Shopify's Webhook Documentation for more information.

_storage hash variable

The _storage hash can be used to persist values between invokations of your script.

if _storage["count"].nil?
    _storage["count"] = 0
else
   _storage["count"] = _storage["count"] + 1
end

puts "count is #{_storage["count"]}"
_storage['string text'] = 'some text'

The value of _storage is automatically serialised as JSON and saved after every successful invokation of your script.

Invoking Scripts

Invokation via Recurring Timer Triggers

You can choose to invoke your script via Recurring Timer Trigger using a Workflow.

To do this, click the "Workflows" link in the top menu.

Highlighting the Workflows link in the top menu

Then click the New Workflow button.

Highlighting the New Workflow button

Then choose from the available Recurring Timer Triggers

Highlighting the Recurring Timer Triggers available within a new Workflow.

We currently allow the following Recurring Timer Triggers:

  • cron/5 - A trigger that will invoke your script every 5 minutes
  • cron/10 - A trigger that will invoke your script every 10 minutes
  • cron/15 - A trigger that will invoke your script every 15 minutes
  • cron/20 - A trigger that will invoke your script every 20 minutes
  • cron/30 - A trigger that will invoke your script every 30 minutes
  • cron/60 - A trigger that will invoke your script every hour

Once you have selected your trigger, select the script you would like to run and name your workflow.

Invokation via Shopify Events

You can choose to invoke your script via Shopify Events using a Workflow. Shopify Events are essentially invoked by Shopify Webhooks.

To do this, click the "Workflows" link in the top menu.

Highlighting the Workflows link in the top menu

Then click the New Workflow button.

Highlighting the New Workflow button

Then choose from the available Shopify Events.

Highlighting the Shopify Event Triggers available within a new Workflow.

Once you have selected your trigger, select the script you would like to run and name your workflow.

Invokation via Online Store

You can choose to invoke your script when a vistor on your Shopify Store visits the App Proxy URL for your script.

The App Proxy URLs for a script take the form of: your-store.myshopify.com/tools/Script Ninja?uuid=YOUR_SCRIPT_UUID.

Enabling Invokation via Online Store

By default, invokation via the online store is disabled. To enable invokation, go to your script and click the Settings tab.

Highlighting the Settings Tab when viewing a Script.

And ensure that the ENABLE SCRIPT TO BE INVOKED FROM ONLINE STORE checkbox is enabled.

Highlighting the ENABLE SCRIPT TO BE INVOKED FROM ONLINE STORE checkbox.

Once enabled, you can now invoke the script from the App Proxy URL above the checkbox.

Highlighting the URL that you can invoke the Script from.

Rendering output to Online Store

A script can output HTML content to the App Proxy URL using the special LIQUID constant, for example:

LIQUID = <<-HTML
    <img src="https://via.placeholder.com/350" />
    <p>The time is #{Time.now}</p>
HTML

Making Outbound HTTP Requests

A script can make HTTP request using either Net::HTTP as part of Ruby's standard library, or using the HTTParty Ruby Gem.

# Making an HTTP GET Request
response = HTTParty.get "https://example.com"
puts response.code
puts response.headers
puts response.body

# Making an HTTP POST Request
response = HTTParty.post('https://example.com/handle', 
    body: { subject: 'This is the screen name', 
               issue_type: 'Application Problem', 
               status: 'Open', 
               priority: 'Normal', 
               description: 'This is the description for the problem'
             }.to_json,
    headers: { 'Content-Type': 'application/json' } )

Included Gems

The following GEMs are available to use within the Script Ninja Environment:

  • activemodel (6.0.2.1)
  • activemodel-serializers-xml (1.0.2)
  • activeresource (5.1.0)
  • activesupport (6.0.2.1)
  • builder (3.2.4)
  • concurrent-ruby (1.1.6)
  • dropbox_api (0.1.18)
  • faraday (1.0.0)
  • graphql (1.10.5)
  • graphql-client (0.16.0)
  • httparty (0.18.0)
  • i18n (1.8.2)
  • jwt (2.2.1)
  • mime-types (3.3.1)
  • mime-types-data (3.2019.1009)
  • mini_portile2 (2.4.0)
  • minitest (5.14.0)
  • multi_json (1.14.1)
  • multi_xml (0.6.0)
  • multipart-post (2.1.1)
  • mysql2 (0.5.3)
  • nokogiri (1.10.9)
  • oauth2 (1.4.4)
  • pg (1.2.2)
  • rack (2.2.2)
  • sequel (5.30.0)
  • shopify_api (9.0.2)
  • thread_safe (0.3.6)
  • tzinfo (1.2.6)
  • zeitwerk (2.3.0)
© 2022 Little Bird Electronics Pty Ltd