In an organisation not all functions are initated by people.

In this guide we cover using Node.js to create functionality that is initiated automatically for the organisation.

The function can be initiated based a time schedule or event from another system ie when data changes.

The mydigitalstructure Javascript framework includes a Node.js module that can help with building automation apps.

It uses similar techniques to those used in the standard browser based library.

If you have any questions please email as at

Let's get the tools you will need

When developing & testing we will run the Node.js engine on your local computer.


Go to and follow the instructions.


Go to and click 'Clone or download'.


Using your text editor (as you installed in the getting started guide) open the folder with the starter app in it.


This folder includes all the files you will need to run the starter app.

learn.js is contains example code that you can use to learn from.


You can use the terminal/console that comes with your computer operating system; the instructions below are based on the MacOS Terminal.

To run the learn.js example, navigate to the folder containing learn.js and type node learn.js and press enter.

You will then see the output based on the console.log() and mydigitalstructure._util.message() calls within the learn.js code. You can now start to modify the code, save the file and then re-run node learn.js to see your changes.

To see debug information from the mydigitalstructure library, in the settings.json file set the "testing.status" and "testing.showData" to "true".

You can also add testing/debug messages in your code using mydigitalstructure._util.message(text or data, context). If the data is a JSON object it will be stringified to show in the console.


Once you are happy that the code is fit to be used by the organisation, it's time to put it to work.

We are using the AWS Lambda cloud service to host the app, but you can use any service that supports the Node.js engine.

The index.js file is structured to work with the AWS lambda service. It is similar to learn.js except that all the code is wrapped in exports.handler = function (event, context) { [functional code] }. The file name can be anything, we are using index.js as this is what AWS Lambda expects by default.

To run index.js on your local computer you will need to install the lambda-local node module.

Once you have it installed, you can run your code in the terminal as lambda-local -f index.js.

The package.json contains all the information that the Lambda service needs to host your application - you can edit (at the least) the name, description, author & keywords.


The Node.js code needs to compressed into a zip file so it can be uploaded to Lambda.

Using the terminal, navigate to the folder containing the code and run
zip -r ../ *


If you don't already have an AWS account, then sign up for the free version.

Now that you have an AWS account, you need to log on and navigate to the Lambda service page.


Click Create function and then select Author from scratch.

Enter a Function name eg mydigitalstructure-learn-app.

Make sure Node.js is selected.

Click Create function


Make sure you check the timeout setting, the default is 3 seconds!

In the Function code section, set Code entry type to Upload a .zip file.


Click the Actions button, select Upload a .zip file, and the select the zip file on your computer, then click Upload.


You will then see the code in the Lambda editor.


The Handler is set to index.handler by default and as the main file is named index.js then you can leave it as is.

You can edit the code in the editor to have a play, but just be aware that if you reload using the zip file upload the edits will be lost.


Now that the node.js code has been uploaded you can test run it.


To test the Node.js app you need to set up some test data that will be sent to the app. In this sample app the data is then logged in the mydigitalstructure console logs section as an example of a invoke method.

Click the Test button.

You can just use the Hello World template data as a start.

Enter an Event name (eg learndata) and click Create.

The default timeout for Lambda is 3 seconds. To make this a longer duration, scroll down to Basic Settings and click the Edit button and increase the timeout to say 5 minutes (maximum is 15 minutes) and click Save.

Now you can test the code by clicking the Test button again.

The code will run and you will see the console outputs and any errors. If it has run successfully, log on to the go to DEBUG LOGS.

Once the app tests successfully, you can schedule it to run as required by the organisation.


In this example we will schedule the app to run once a day at 4AM UTC.

The AWS Lambda service uses the cron & rule syntax to set up the schedule. In this example we are using cron and the expression is cron(0 4 * * ? *).

You can use this Online CRON Expression Generator to create a CRON expression, but just remember to remove the first "0" as that is seconds and AWS does not support it.

On the function details page, click the Add Trigger button and select CloudWatch Events/Event Bridge.

Set Rule to Create a new rule and give it a Rule name (eg mydigitalstructure-learn-schedule-1)

Make sure Schedule expression is selected and copy and paste in cron(0 4 * * ? *) and click Add.

You can set up multiple triggers for the same lambda function and provide different event data for each trigger using the Constant (JSON text) option.

Trigger Data

It's now set up and ready to run!

Use the following mydigitalstructure methods to manage local data, data on and your apps controller code.
eg mydigitalstucture.init()
Item Description
Log on to the using settings.json data.
Add your controller code:
  • name: controller name
  • code: JavaScript code
You can multiple by using an array.
Invoke (run) your controller code:
  • name: controller name
  • param: object to be passed to the controller as first argument
  • data: object to be passed to the controller as second argument
Set data into the local temporary data space:
  • scope: scope to store the data in eg 'app-contacts'
  • context: context to store the data in eg 'current' (optional)
  • name: context to store the data in eg 'person' (optional)
  • value: the data to be stored
Get data from the local temporary data space:
  • scope: scope to store the data in eg 'app-contacts'
  • context: context to store the data in eg 'current' (optional)
  • name: context to store the data in eg 'person' (optional)
  • valueDefault: a default value to return if no data found
Log on to the - better to use .init() and settings.json.
Log off from
Save data on
  • object: the object eg 'contact_person'
  • data: data to be sent to
  • callback: controller name to call when call to complete
Retrieve data from using the query language:
  • object: the object eg 'contact_person'
  • fields: object fields to be returned
  • summaryFields: object summary fields to be returned
  • filters: field filters to be applied to the search
  • sorts: field sorts to be applied to the search
  • options: rows:
  • customOptions:
  • callback: controller name to call when call to complete
Invoke a method directly on
  • object: the object eg 'contact_person'
  • data: data to be sent to
  • callback: controller name to call when call to complete
Only use this if .retrieve() & .save() not approriate.
Send a message to the console:
  • message: message text
  • context: context of the message eg the controller name
Invoke a callback controller when complete:
  • onComplete: controller name
  • onCompleteWhenCan: controller name
(param, field, options)
Get a field value from an object:
  • param; the object with the fields
  • field; the field name
  • options; default:, set:
  • exists: does the field exist
  • value: the field value
(param, field, value, options)
Set a field value in an object:
  • param; the object
  • field; the field name
  • value; the value
  • options; onlyIfNoKey:
  • exists: does the field exist
  • value: the field value