Create and upload a custom snippet

Create a custom process snippet to save a frequently-used process script as a .json file, which can be inserted into any process on your database.

About this task

A custom snippet is composed of several objects or properties, some required and others optional, all using standard JSON syntax. The objects and properties are described in Table 1.

Table 1. Snippet objects and properties
Snippet component	Required?	Description
snippetId	Required	A unique identifier for the snippet. Example: `"snippetId": "ITERATION_SNIPPET",`
name	Required	A name for the snippet. Example: `"name": "Iterate over members in a hierarchy",`
description	Required	A description of the snippet. Though this is a required property, it can be empty if you don't want to provide a description. Example: `"description": "This snippet iterates over members in a hierarchy and performs an action on each leaf member",`
auxliaryVariables	Optional	Auxiliary variables must be included and defined in the snippet only if your script includes auxiliary variables. These variables are used in the script during runtime. For example, a counter variable for a WHILE loop. Auxiliary variables are specified as an array of the auxiliary variable names that are present in the script. Example: `"auxiliaryVariables": [ "index", "vElement" ]`
variables	Optional	Variables must be included and defined in the snippet only if your script includes variables. These are the variables that must be initialized before inserting the snippet into a process. Variables are specified as an array, using the variable object format described later in this documentation. Example: `"variables": [ { "variableName": "vDimension", "description": "Parent dimension of the hierarchy", "valueDefinition": { "type": "DIM", "defaultVal": null } }, { "variableName": "vHierarchy", "description": "Hierarchy to iterate", "valueDefinition": { "parent": "vDimension", "type": "DIM_HIER", "defaultVal": null } }],`
script	Required	An array of strings containing the process code. Each string value will be a new line when the snippet is inserted in the process editor. In the script, variables are referenced using the format `vName:AssignedVariableName`, where `AssignedVariableName` is the name you assign with the variableName property. In the script, variable values are referenced using the format `vValue:AssignedVariableName` Auxiliary variables are referenced using the format `aux:AuxiliaryVariableName`, where `AuxiliaryVariableName` is an auxiliary variable name that has been defined in the auxliaryVariables property. Example: `"script": [ "script line 1;", "script line 2;", "script line 3", ]`

If your .json file includes variables, they must be specified using this object format:

 "variables": [
                {
            "variableName": "name",
            "description": "Brief description",
            "valueDefinition": {
                "parent": "parentOfHierarchy",
                "type": "aValidTye",
                "defaultVal": "value"
            }
        }],

Table 2. Variable object components
Variable component	Required?	Description
variableName	Required	The name of the variable. Example: `"variableName": "vDimension"` Once the variable name is defined, it is referenced in the script using the format `vName:AssignedVariableName`. For example, after defining `"variableName": "vDimension"` , you would reference the variable as `vName:vDimension` in the script object.
description	Optional	A brief description of the variable. Example: `"description": "Parent dimension of the hierarchy"`
valueDefinition	Required	A value definition object containing these properties: parent The parent dimension of the hierarchy that is referenced by the variable. This property is required only if the type property is `DIM_HIER`. type The type of value that the variable references. Valid types are: `CUB` - a cube `DIM` - a dimension `DIM_HIER` - a hierarchy `STRING` - a string `NUMERIC` - a numeric value defaultVal Optionally, a default value for the variable. Example: `"valueDefinition": { "parent": "vDimension", "type": "DIM_HIER", "defaultVal": null }`

Procedure

Create a new .json file.
Create your custom snippet using the components described in this topic.
Save the snippet.
Open a modeling workbench.
On the Databases tree, expand the database where you want to upload your custom snippet.
Open an existing process in the process editor or right-click the Processes node, then click Create process to open a new process editor.
Click the Script tab on the process editor.
Click the snippet icon , then click Custom.
On the Snippet manager page, click Upload snippets.
Drag and drop or navigate to the .json file that contains your custom snippet, then click Upload.
The custom snippet you uploaded is now available for reuse at any time.
Click Close and then Cancel to dismiss the Snippet upload and Snippet manager pages, respectively.

For details on inserting a custom snippet into a process, see Insert a code snippet into a process.

Example

This example presents a custom snippet that iterates over members in a hierarchy and performs an action on each 0-level member encountered in the hierarchy. The snippet writes member names to a file using the AsciiOutput function, but you could modify the code to perform whatever action you want within the WHILE loop.

To further your understanding of custom snippets, you can work through a complete tutorial to create this exact snippet.

{
  "snippetId": "ITERATOR_OVER_MEMBERS_IN_A_HIERARCHY",
  "name": "Iterate over members in a hierarchy",
  "description": "This snippet iterates over members in a hierarchy and performs an action on each leaf member",
  "auxiliaryVariables": [
        "vSubsetSize",
        "index",
        "vElement"
    ],
    "variables": [
        {
            "variableName": "vDimension",
            "description": "Parent dimension of the hierarchy",
            "valueDefinition": {
                "type": "DIM",
                "defaultVal": null
            }
        },
        {
            "variableName": "vHierarchy",
            "description": "Hierarchy to iterate",
            "valueDefinition": {
                "parent": "vDimension",
                "type": "DIM_HIER",
                "defaultVal": null
            }
        },
        { 
            "variableName": "vSubset",
            "description": "Subset created to hold all members ",  
            "valueDefinition": {
                "type": "STRING",
                "defaultVal": "temporary"
            }
        }],
    "script": [
            "# Iterate over members in a hierarchy",
            "vName:vDimension = 'vValue:vDimension';",
            "vName:vHierarchy = 'vValue:vHierarchy';",
            "vName:vSubset = 'vValue:vSubset';",
            "HierarchySubsetCreate(vName:vDimension, vName:vHierarchy, vName:vSubset, 1);",
            "HierarchySubsetIsAllSet(vName:vDimension, vName:vHierarchy, vName:vSubset, 1);",
            "aux:index = 1;",
            "aux:vSubsetSize = HierarchySubsetGetSize(vName:vDimension, vName:vHierarchy, vName:vSubset);",
            "WHILE (aux:index <= aux:vSubsetSize);",
            "   aux:vElement = ElementName(vName:vDimension, vName:vHierarchy, aux:index);",
            "   IF ( ElementLevel(vName:vDimension, vName:vHierarchy, aux:vElement) = 0);", 
            "       # Do something with vElement such as a write it to a file;",
            "       AsciiOutput('model_upload/snippet.txt', aux:vElement);",
            "   ENDIF;",
            "   aux:index = aux:index + 1;",
            "   aux:vElement = ElementName(vName:vDimension, vName:vHierarchy, aux:index);",
            "END;"
      ]
}