plugins

Randomise your data in an instant

Why would you need to obfuscate/scramble your data?

The most common reason why you would need to obfuscate/scramble your data is if you need to send your data to third parties. One way to do it, is to randomize the values. The metadata (cubes, dimensions and elements names) will still be intact but the data will be randomised.
You could do it manually by doing a proportional spread but it could be time consuming if you are working on large cubes. A new way to randomise your data is now available with Arc and the randomisator plugin.

How does it work?

In just three quick steps, you will be able to randomise data for any cubes:

  1. Select the cubes you want to randomise.
  2. Select the target folder where the new .cub files will be created.
  3. Click Randomise button.

The plugin will create new .cub files in the target folder with random data. Therefore, there is no risk to mess-up your actual data as this plugin will create new .cub files.

See it in action!

Where to find it?

The randomisator plugin is not part of the default plugins when you install Arc. However it is part of the samples plugins which you can find on the cubewise-code/arc-plugins-samples github page.

How to set-it up?

To add one of these plugin to your Arc installation, you just need to download the folder from GitHub:

Paste it in your Arc/plugins installation folder:

Then refresh your browser and clear the cache. You should now be able to see it under Tools:

Where to share Arc plugins

A Arc plugin is a folder which contains as minimum, two files:

  • plugin.js: The plugin definition and the controller.
  • template.html: The look and feel of your plugin.

All plugins are stored in the plugins folder

  • :\Arc\plugins

Share your plugin with someone

To share your plugin, you just need to zip this folder and send it to someone.

Share your plugin on the Cubewise forum

To share your plugin with all the Arc community, you can upload your zip file or share your Github link on the Arc forum.

Share your plugins on Github

Github is a web platform where you can share your code publicly for free. Sharing your plugins on Github will enable the community to get the latest version of your plugin.

1 - Create a Github account

To be able to share your plugin on Github, you will need first to create an account. It's free if you agree to share your code publicly.

2 - Create a README.md file

The README.md file can be used to explain what your plugin does and how to use it:

An example of a README file can be found here.

Arc Plugins on Github

You can also find on Github all the latest Arc plugins by Cubewise CODE. Checkout the following repository:

Execute TM1 REST API queries

The TM1 REST API plugin will help you to get more familiar with the TM1 REST API. You can execute pre-written GET, POST, PATCH and DELETE request or write your own requests.

The plugin will then show the JSON response that the TM1 REST API sends back:

Add this plugin to your environment

  1. Download the folder.
  2. Paste the folder insite your plugins folder (Arc\plugins).
  3. After clearing the cache you should now see the plugin.

How to create your plugins

If you do not know what is a plugin in Arc, you should read first this Help article:

Creating a Plugin

The easiest way to create a plugin is to copy an existing example and then update as required. The steps to do this are as follows:

  1. Copy the directory containing the plugin. For example, Arc\plugins\bedrock-cube-clone.
  2. Edit the plugin.js file updating the name of the plugin so it is unique. A good idea is to use your name or domain as a prefix to your plugins. The name must be updated in two locations, in the definition and on the service/directive (see below).
  3. Update the rest of the plugin information and refresh the page.

The README file in the plugins directory contains a description of each of settings you can update when defining a plugin:

There are 4 arguments to pass through to the plugin function:
    name:   The name to use for the plugin, this must be unique or an error will occur.
            Use your name or domain as a prefix to make it unique
    label:  The label is what you will see in the menu 
    type:   The type of plugin, options are: page, menu/dimension, menu/cube, menu/process, menu/chore
    options: Extra (optional) options for the plugin as an object:
        icon:           A font-awesome class for the icon you want to display
        instanceName:   Restrict the plugin to a particular TM1 instance
        objectName:     Restrict the plugin to a particular TM1 object
        description:    A description of what the plugin does
        menu:           A parent menu to add the plugin to: dimensions, cubes, processes, chores, administration, tools
        version:        The version of the plugin
        author:         Your name
        url:            A URL that people can use to find out more details about the plugin

After defining a plugin you must create either a service (for menu plugins) or directive (for pages)
The service/directive name must match the plugin name used above
Menu plugins MUST implement one interface execute(instance, name)

Executing a TI Process from a Plugin

One of the easiest things to add to a plugin is executing a process or chore. You can see some examples of this in all of the menu plugins: bedrock-cube-clone, bedrock-dimension-clone, general-ledger-load and process-execute

Before you can execute a process or chore you need to include the $tm1 service in your plugin, if you have copied an existing plugin it will already be there.

The $tm1 service has following parameters to call a process and chore:

  • $tm1.processExecute(instanceName, processName, parameters)
  • $tm1.choreExecute(instanceName, processName)

If you pass 2 parameters to processExecute leaving the parameters blank Arc will retrieve the list of parameters and present the user with a dialog box for input.

If you want to execute the process directly without user input you should pass through the parameters:

$tm1.processExecute(instance, "Bedrock.Dim.Clone", [
    {
        Name: "pSourceDim",
        Value: name
    },{
        Name: "pTargetDim",
        Value: newName
    }
]).then(function(result){
    if(result.success){
        // It has finished with success
        $rootScope.reloadInstance(instance);
    }
});

Both processExecute and choreExecute return a promise (then function) that can be used to update the UI after the process is complete. If the process you are running is add or deleting objects your can refresh the menu on completion using $rootScope.reloadInstance(instance); See above example.

How Plugins work

What is a plugin?

A plugin is a functionality that you can add to Arc. Arc comes with a few plugins, you can see the full list in Arc/plugins folder:

There are two types of plugins in Arc: pages and menu items.

Page Plugin

A page plugin can be used to building nearly anything you want, it has full access to the REST API and is only limited by your imagination. It is created by building an Angular directive, you really don’t need to know much about this, start by copying an existing plugin. All page plugins will apear under Tools in the left bar menu:

The pages you create can be used either for all TM1 instances or can be designed for a specific application. Some examples of what you can build are:

  • Manage security
  • Retrieve and update security
  • REST API explorer
  • Administration page with links to important TI or processes that you run each month.
  • Bedrock admin page with descriptions of TI easy execution.
  • Apliqode admin pages to provide a custom UI to all of the cool stuff in Apliqode.

Menu Plugin

The menu plugins appear as a sub item on the menu. The menu plugins can be configured to appear by object type, instance and/or object name. It can be used to customise the Arc interface so it is quick and easy to do your common day to day tasks. If you are doing things each day or month consider building a plugin.

For example, a plugin already exists Bedrock Clone which is going to run the Bedrock.Clone process for the specific dimension:

There are lots of things you could use the plugin for such as:

  • Add a sub menu to each process to execute it.
  • Add a sub menu to clone an object.
  • Add a sub menu to rename objects.
  • Add a sub menu to delete objects.
  • Add all of the related load processes for a cube as a sub menu. (see, general-ledger-load plugin).

The important part of the menu plugin is the function this.execute(instance, name), each menu plugin must contain this function. It is executed when you click on the menu item and passes through to the plugin the name of TM1 instance and the name of the TM1 object.

For example if you open the C:\Arc\plugins\bedrock-dimension-clone\plugin.js file, you can see that the this.execute command run the process Bedrock.Dim.Clone process:

How Plugins are loaded

The plugins are loaded from the plugin directory in the same location as Arc. The plugins are processed in the following way:

  1. The Arc application is loaded in the browser or refreshed.
  2. Any plugin.js files in the plugins directory and its sub-directories are combined and loaded with the Arc application. You can disable loading of a particular plugin via the plugins.yml in the plugins directory.
  3. Calling $rootScope.plugin function adds the plugin to Arc.
  4. The directive or service is added to Arc app.
  5. For page plugins they are added to the menu, menu items are added as a sub menu based on the criteria in the plugin.

Plugins are loaded from file each time you refresh your browser so development is easy, change the file, refresh the page and see if it works. You can also use your favourite browser developer tools to debug your plugin in the browser, in Chrome press F12 and go to the Sources tab, there you will see the plugins file by expanding the _ folder. The plugins fileis named plugins_{version}.js