Scripts

Fibery supports automations in the form of rules and action buttons. The former allows actions to be performed automatically when a trigger condition is met. The latter allows users to run a set of pre-determined actions.

There can be times though when you want an automation to do something a bit more complicated, something which might not be possible using the existing actions. In these cases, scripting can help.

</> Script

A script is written in the script window, available as one of the possible automation actions.

All scripting is written using the Javascript language. You don't need to be a complete master, but having a basic understanding will help.

Services

A script has access to the following services: fibery, http and utils.
Use the fibery service to perform some operations on your Fibery workspace.

const fibery = context.getService('fibery');

Use http to make arbitrary requests on the web.

The utils service has some commonly-used utilities.

Once a service has been defined, the functions available for that service can be used, e.g.

fibery.deleteEntity("Tasks/Task","6a5ca230-da86-11ea-a1b3-ff538984283f")

Await

The available Fibery functions are asynchronous, so you will need to use the await keyword when calling them, and since some of the functions return a result, you will typically want to save the result in a variable, e.g.

const newTask = await fibery.createEntity("Tasks/Task",{"Name":"New Task"});

Arguments

When an action button is run or a rule is triggered, there are pieces of data that are available to be accessed within the script.

This includes the entity (or entities) that was (were) selected/active when the button was pressed/trigger occurred, and the identity of the user that pressed the button/triggered the rule.

The former is available as

args.currentEntities

which is an array of objects.

It will look something like this:

[
  {
    "Public Id": "1",
    "Id": "a129d810-f8a0-11e8-88d2-3d1a5c86c61f",
    "Creation Date": "2018-12-05T15:15:41.738Z",
    "Modification Date": "2019-09-27T08:48:08.873Z",
    "Rank": 500000,
    "Name": "Swim farthest",
    "State": {
      "Name": "Done",
      "Id": "70df7a70-f8a0-11e8-a406-9abbdf4720ab"
    },
    "type": "Tasks/Task"
  },
  {
  ...
  }
]

The latter is available as

args.currentUser

which is an object that will typically look something like this:

{
  "Public Id": "1",
  "Id": "fe1db100-3779-11e9-9162-04d77e8d50cb",
  "Email": "vincent@gattaca.dna",
  "Creation Date": "2019-02-23T14:47:49.262Z",
  "Modification Date": "2019-09-27T08:17:46.608Z",
  "Name": "Vincent Freeman",
  "Role": {
    "Id": "57d5dd70-b9df-11e9-828d-51c8014f51c9",
    "Name": "Navigator"
  },
  "type": "fibery/user"
}

Note: If a rule has been triggered by something other than a user action, e.g. when the value of a formula field containing the Today() function changes, then args.currentUser will return null.

Activity log

The Activity log for each automation is the place to look to see when an automation has been executed and what happened.

Debugging

When running a script from a button press, if everything goes OK, there will be a pop-up message to let you know:

Sometimes, things might not always go as planned. It can be useful to add steps to the script that report relevant information to the browser console, e.g.

console.log(args.currentEntities[0]);

It varies from browser to browser; in the case of Chrome, the browser console can be opened with Ctrl-Shift J.

Fibery service workspace functions

The following functions are available in scripting for the fibery service:

* the executeSingleCommand function allows a script to run any Fibery API command. This gives tremendous flexibility, but requires a bit of experience with the low-level Fibery API that is beyond the scope of this article.

Function arguments

The type argument is the name of the database, e.g. "Task".

If there is more than one database with the same name, you should prefix with the workspace name, e.g. "Project management/Task"

The id / itemId is the UUID of the entity, e.g. "fe1db100-3779-11e9-9162-04d77e8d50cb"

field and fields are the name(s) of the entity's fields, as a string or an array of strings, e.g. "Creation date" or ["Name","Assignees"]

values is a object containing one or more field name/value pairs, e.g.

{
  "Name" : "My entity",
  "Effort" : 10
}

state is the name of a workflow state, as a string, e.g. "In Progress"

secret is a UUID string that represents a collaborative document, e.g. "20f9b920-9752-11e9-81b9-4363f716f666". It is the value returned when reading a rich-text field and the value used to access/manipulate that rich-text field's contents.

userId and authorId are UUIDs for Fibery users in the workspace.

Note: the button presser's Id is accessible as args.currentUser['Id']

Http service functions

The following functions are available in scripting for the http service:

These functions represent standard http request methods.

Utils service functions

The following functions are available in scripting for the utils service.

As the name suggests, getEntityURL allows you to generate a URL (entity view) for the selected entity.

uuid returns a string which can be used when creating a new entity, if for example, you need to refer to that entity before the async createEntity function has completed.

Example

Here is an example of what you can use scripting to achieve:

Suppose you want to assign yourself to a number of tasks (which may or may not already have other users assigned). You might also want to remove yourself from a bunch of tasks.

Of course, you could manually open each task and add/remove your name to/from the list of users, but with a button that calls a script action, you can automate this process:

Here's the script:

const fibery = context.getService('fibery');

// do this for all tasks
for (const entity of args.currentEntities) {
    // make sure you have the information from the Assignees field
    const entityWithAssignees = await fibery.getEntityById(entity.type, entity.id, ['Assignees']);

    // extract the IDs of all users currently assigned
    const assigneeIds = entityWithAssignees['Assignees'].map(({ id }) => id);

    // get the ID of the user who pressed the button
    const userId = args.currentUser['id'];

    // if the user is already assigned...
    if (assigneeIds.includes(userId)) {
        // ... then remove them
        await fibery.removeCollectionItem(entity.type, entity.id, 'Assignees',userId);
    }
    else {
        // otherwise, add them
        await fibery.addCollectionItem(entity.type, entity.id, 'Assignees', userId);
    }
}