Flex Scripting: Best Practices – Support Hub

May 19, 2024 05:43
Updated

The scripting facilities provided by Flex allow for extensive client-specific customisation and programmatic system control. Although this capability is a boon for Flex users, it is very easy to abuse the scripting capabiliies, which can lead to system slowness, complicated logic paths and maintainence issues. This part of the documentation provides guidance on how to write scripts effectively and how to package them into manageable units.

Groovy

Flex script are written in Groovy, which is a programming language built on top of the Java Virtual Machine. Groovy is simple, yet powerful language, and it would be worthwhile any script author to familiarise themselves with the language and its features. This is out of scope here, but the following links will help you to get started:

Important Note

Be careful with 'long' numbers (i.e. all Flex IDs).

It is strongly recommended that Flex ID numbers, when written, are explicitly appended with the 'Long' type suffix 'L'.

For example:
List<Long> writeACL = [123456]

The above may look fine, an explicit list of long numbers, does it not?
No. The number is a literal 123456 and by default is an int. This can result in Flex SDK throwing errors related to casting, resulting in unnecessary support incidents and unnecessary developer involvement.

The correct way to write this would be: List<Long> writeACL = [123456L]

The number type suffix 'L' forces it to be a Long type.
When you are hard-coding / specifying a Flex ID, always add the number type suffix 'L'.

Use an IDE

Script authors should always use an IDE to write script as this provides code completion, code formatting and the ability to write unit tests. The Flex development team recommends the IntelliJIDE, as this is what is used internally and has good support for the features a script author might need.

You can also write scripts and compile them to a JAR, which can subsequently be referenced by Flex within an external action configuration. Please see Flex Scripting: Writing External Scripts for further information.

An example project exists in GitHub to demonstrate writing scripts using an IDE.

Format your scripts

Scripts should always be formatted well, with suitable spacing and indentation. Doing this will make them easier to understand and support. An IDE will allow you to format your scripts automatically.

Store scripts in source control

Scripts should always be stored in source control (in BitBucket if you are a Dalet employee). Source control provides a secure, central location to store these system-critical components, and provides change tracking and accountabilityy. Tagging will also allow you to mark an entire suite of scripts with a given label, which can be used to mark a known state of the scripts. For example, you could tag a scripting source respository before attempting a big multi-script change, which would allow you to rollback to a known state if problems arise.

If you are not using External Scripts, you can move scripts from source control into Flex via copying and pasting them into an action’s config.

Script length

You should aim to keep your scripts as short as possible. Long scripts are complicated and will be difficult to maintain. If a script is becoming unweidly in length, split the action in 2.

Peer reviewing

There is no reason why scripts cannot be reviewed by someone else on the Flex team, or even the development team (if the scripts are being written by Dalet resources). A peer review is a great way to learn better/alternative approaches and to prvide a sanity check.

Beware of script “hacking”

It is not uncommon for script authors to make changes to existing scripts without really understanding the functionality. For example, an original version of a script might save changes to an asset’s metadata at the start of a script. A subsequent edit makes another change and save to the metadata further down the script, which then means you are updating the metadata twice. This causes extra system load and should be avoided.

Unit testing

Flex scripts can be unit tested, which can be written to ensure that the script performs as expected. Although writting these tests takes time, they can be used to confirm that any additional edits will not break existing functionality.

def execute() {
    def assetService = flexSdkClient.getAssetService()
    def assetPl = NewAssetPlaceholder.builder()
            .type('media-asset')
            .name('demoasset')
            .build()
    def asset = assetService.createAsset(assetPl)
    return asset.id
}

We can add a test to ensure that we create an asset of the expected type and that the ID is returned:

import com.ooyala.flex.model.asset.Asset
import com.ooyala.flex.model.asset.create.NewAssetPlaceholder
import com.ooyala.flex.plugins.GroovyScriptContext
import com.ooyala.flex.sdk.FlexSdkClient
import com.ooyala.flex.sdk.services.enterprise.AssetService

def "new asset creation"() {
    
    final long ASSET_ID = 123L

    def flexSdkClient = Mock(FlexSdkClient)
    def assetService = Mock(AssetService)

    def target = new CreateNewAssetScript()

    given:
    flexSdkClient.getAssetService() >> assetService target

    setFlexSdkClient(flexSdkClient as FlexSdkClient)
    def asset = Asset.builder()
            .id(ASSET_ID)
            .build()

    assetService.createAsset(_ as NewAssetPlaceholder) >> asset

    when:
    def id = target.execute()

    then:
    id === ASSET_ID
}

See the example project to see how to set up unit tests within a scripting project.

Further advice

The following pages are useful guides to help accelerate the writing of Flex scripts: