Script Module

The script module is automatically imported as script.

Represents the currently running script. The script object includes the following:

  • _id (ObjectId) the script identifier

  • access (Number) the acl level of access to the current in-context subject

  • arguments (Object) the script arguments object. In triggers, there are old and new properties that represent the original and modifications made to the access context subject.

  • depth (Number) the 1-indexed script depth (a trigger firing trigger would have a depth of 2).

  • label (String) the script label.

  • env (Object) the current api environment

    • host (String) the api host (api.medable.com or api.dev.medable.com)

    • name (String) the environment name (production/development)

    • url (String) the api base endpoint (eg. https://api.medable.com/my_org/v2)

    • version (String) the current api version string

  • org (CortexObject)

    • _id (ObjectId) the org identifier

    • code (String) the org code

  • originalPrincipal (ObjectId) The identifier of the principal who originally called the script. This may differ from the script principal if it was configured to run as a specific account.

  • principal (CortexObject)

    • _id (ObjectId) the identifier of the principal who called the script.

    • email (String) the principal's email address

    • name (Object)

      • first (String) the principal's first name

      • last (String) the principal's last name

    • roles (ObjectId[]) a list of the principal's assigned org roles

    • tz (String) the timezone for the current principal. Defaults to org tz if no timezone is available for the principal.

  • type (String) the script type (trigger, route, job)

Methods

as(principal, options, function) gc() getCalloutsRemaining() getElapsedTime() getMemoryFree() getMemoryUsed() getNotificationsRemaining() getOpsRemaining() getOpsUsed() getTimeLeft()

as(principal, options, function)

Calls function as principal. script.as() calls can also be nested, and will always obey parent restrictions (excluding principal scope). Also available as a decorator (@as).

Arguments

  • principal (String) The email or identifier of the new script principal.

  • options (Object) An options object that limits what's accessible inside function.

    • acl (Object)

      • safe (Boolean=true) If true, automatically adds bypassCreateAcl, grant and skipAcl to acl.blacklist

      • blacklist (String[]=null) Adds blacklisted options to the current set, which are filtered out of all api calls. For example, adding skip will cause org.objects.accounts.find().skip(1).passthru() to ignore the skip option.

    • principal (Object)

      • roles (ObjectID[]=null) Adds roles to the current principal. To get an empty set of starting roles, call the script anonymously.

      • scope (String[]=null) Overrides the current principal scope. To use the same parent scope, it must be passed to script.as().

      • grant (Number=0) Sets the grant level of the calling principal. This grant level will apply to all acl operations, including list and reference read/write-through, but not to nested calls to script.as(). Negates the need to use the grant() cursor modifier.

      • skipAcl (Boolean=false) If true, applies skipAcl (for list query results) to all acl operations, including list and reference read/write-through, but not to nested calls to script.as(). Negates the need to use the skipAcl() cursor modifier.

      • bypassCreateAcl (Boolean=false) If true, applies bypassCreateAcl to all create operations, including list write-through, but not to nested calls to script.as(). Negates the need to use the bypassCreateAcl() cursor modifier.

    • modules (Object)

      • safe (Boolean=true) if true, adds a number of modules to the module blacklist (including api, cache, connections, console, debug, http, logger, notifications, objects.transfer, response, script, session).

      • whitelist (String[]=null) If set, these will be the only available api interfaces. If nesting script.as(), the parent module.whitelist is also evaluated.

      • blacklist (String[]=null) If set, these api interfaces will not be callable. If nesting script.as(), the parent module.blacklist is also evaluated.

  • function (Function) The function to be called as principal.

Returns

  • value (Object) Returns the result of the function argument.

gc()

Runs garbage collection and returns the number of bytes freed.

Returns

  • value (Number)

getCalloutsRemaining()

Returns the number of http callouts (http module requests) available to the current running script. Check the Execution Limits in your org configuration for the maximum number of http callouts.

Returns

  • value (Number)

getElapsedTime()

Returns the number of milliseconds since the start of the script.

Returns

  • value (Number)

getMemoryFree()

Returns the number of bytes free for use in-script.

Returns

  • value (Number)

getMemoryUsed()

Returns the number of bytes of memory currently allocated to the script.

Returns

  • value (Number)

getNotificationsRemaining()

Returns the number of notifications.send() calls available to the current running script.

Returns

  • value (Number)

getOpsRemaining()

Returns the number of byte code operations available to the script.

Returns

  • value (Number)

getOpsUsed()

Returns the number of byte code operations consumed by the script.

Returns

  • value (Number)

getTimeLeft()

Returns the number of milliseconds remaining to the script before a timeout error is triggered.

Returns

  • value (Number)

script.as() example

// route called anonymously
const req = require('request'),
      name = req.body.name; // "James"      

// create an object as jane@example.org
const _id = script.as(
  'jane@example.org',
  () => {
    return org.objects.c_ucumber.insertOne({c_name: name}).execute();   
  });

// update the document as john@example.org (updater will be john@example.org)
script.as(
  'john@example.org',
  {
    principal: {
      grant: consts.accessLevels.update        
    }
  },
  () => {   
    org.objects.c_ucumber.updateOne({_id: _id}, {$set: {c_name: `${name} ${name}`}}).lean(false).execute();   
  });

// read the document with: 
//   1. a role that grants `read` in the defaultAcl (a skipAcl() cursor modifier doesn't work because of the acl.safe=true default.)
//   2. a grant that allows reading the object *and* read-through owner and creator properties.
return script.as(
  script.principal._id,
  {
    principal: {
      roles: consts.roles.CucumberReader,
      grant: consts.accessLevels.read
    }
  },
  () => {   
    return org.objects.c_ucumber.find({_id: _id}).paths('c_name', 'creator.email', 'updater.email').limit(1).toArray()[0];
  });

/*
{
    "_id": "5a29cb64e00aa2e4ed8b1a68",
    "c_name": "James James",
    "creator": {
        "_id": "5a29c923e00aa2e4ed8b19eb",
        "email": "jane@example.org",
        "object": "account"
    },
    "object": "c_ucumber",
    "updater": {
        "_id": "5a29c92fe00aa2e4ed8b19f5",
        "email": "john@example.org",
        "object": "account"
    }
}
*/

Using @as decorator

import { as } from 'decorators';
import { body } from 'request';

class Protected {
  
    @as('admin@example.org', {principal: {skipAcl: true, grant: consts.accessLevels.script, roles: [consts.roles.Owner]}, modules: {safe: false}, acl: {safe: false}})
    static createOne(properties) {

        return org.objects.c_protected.insertOne(properties).execute();        

    }
}

class John {
  
    @as('john@example.com')
    static whoami() {
        return script.principal.name.first
    }
}

// script called as jane@example.org.
const _id = Protected.createOne(body); // ObjectID("5a2c43548664e438e45387cd")
const name = John.whoami(); // "John"
PreviousSchemas ModulesNextSession Module

Last updated