Planning Analytics

Given a recent thread on locking elements in IBM PA (here), I figured I would provide a practical overview on how to apply/remove locks.

In PA, locks can be applied to cubes and elements (locking data) and on dimensions (locking metadata). Locks will block any user and any TI process, which is why locks can very useful. One way to circumvent a lock is to use the function CubeLockOverride.

Below I will focus on the 3 types of locks, as well as on different areas:

• Turbo Integrator processes
• Manual interventions in PAW
• Manual interventions in Architect/Perspectives
• the TM1 REST API

In the article, we will encounter new functions, some functions even are not (yet) recognized in IBM PAW.

Locking/unlocking a cube ( this locks/unlocks the entire cube, no data changes are possible )

Our options include:
- in Turbo Integrator:
     * CubeSetLockStatus( <vCube>, <1=lock|0=unlock> ); (this appears to be an undocumented function, it is not recognized in PAW but the process saves and runs)
     * When a chore runs this process, the username in the }CubeProperties cube becomes 'Admin'
     * CellPutS( <vUser (TM1User() typically) to lock|'' to unlock>, '}CubeProperties', vCube, 'LOCK' );
- manually, in PAW:
     * right-click a cube > Cube operations > Lock cube (if it is currently unlocked) / Unlock cube (if it is currently locked) (a lock icon will appear when locked)
     * editing the cell in the }CubeProperties cube on the measure LOCK and the said cube
- manually, in Architect/Perspectives:
     * right-click a cube in the Server Explorer > Security > Lock (if it is currently unlocked) / Unlock (if it is currently locked)
     * editing the cell in the }CubeProperties cube on the measure LOCK and the said cube
- in the TM1 REST API:
     * POST /api/v1/Cubes('<vCube>')/tm1.Lock|/api/v1/Cubes('<vCube>')/tm1.Unlock (204 No Content) (the username in the }CubeProperties cube becomes the REST API account)

# to test the existence of a cube lock:
If( Dimix( '}Clients', CellGetS( '}CubeProperties', vCube, 'LOCK' ) ) > 0 );
   # the cube is locked
EndIf;

# to lock a cube:
If( CellIsUpdateable( '}CubeProperties', vCube, 'LOCK' ) > 0 );
   CellPutS( vUser, '}CubeProperties', vCube, 'LOCK' );
EndIf;

# to unlock a cube:
If( CellIsUpdateable( '}CubeProperties', vCube, 'LOCK' ) > 0 );
   CellPutS( '', '}CubeProperties', vCube, 'LOCK' );
EndIf;

# Alternatively:
# Security access checkbox is not needed
CubeSetLockStatus( vCube, 1 );

Locking/unlocking an element in a hierarchy of a dimension ( this locks/unlocks all cubes that use this dimension, on the specified element )
No data changes are possible on this element
also, attributes for a locked element cannot be set or changed

Our options include:
- in Turbo Integrator:
     * DimensionElementSetLockStatus( <vDim>, <vElement>, <1=lock|0=unlock> ); (this appears to be an undocumented function, it is not recognized in PAW but the process saves and runs)
     * When a chore runs this process, the username in the }CubeProperties cube becomes 'Admin'
     * CubeLockOverride( 1 );
       CellPutS( <vUser (TM1User() typically) to lock|'' to unlock>, '}ElementProperties_<vDim>', vElement, 'LOCK' );
       CubeLockOverride( 0 );
- manually, in PAW:
     * right-click an element in the Dimension Editor > Lock (if it is currently unlocked) / Unlock (if it is currently locked) (a lock icon will appear when locked)
     * editing the cell in the }ElementProperties cube has never worked
- manually, in Architect/Perspectives:
     * right-click an element in the Subset Editor > Security > Lock (if it is currently unlocked) / Unlock (if it is currently locked)
     * editing the cell in the }ElementProperties cube has never worked
- in the TM1 REST API:
     * Not possible with a POST query towards Dimensions('<vDim>')/Hierarchies('<vHier>')/Elements('<vElement>') and then tm1.Lock|tm1.Unlock
     * Possible via:

         to lock:

# to test the existence of an element lock:
If( CubeExists( '}ElementProperties_' | vDim ) = 0 );
   # the element is not locked
Else;
   If( Dimix( '}Clients', CellGetS( '}ElementProperties_' | vDim, vElement, 'LOCK' ) ) > 0 );
      # the element is locked
   EndIf;
EndIf;

# to lock:
If( CubeExists( '}ElementProperties_' | vDim ) = 0 );
   CubeCreate( '}ElementProperties_' | vDim, vDim, '}ElementProperties' );
EndIf;

# A simple CellPutS works fine provided we override existing locks
CubeLockOverride( 1 );
# If( CellIsUpdateable( '}ElementProperties_' | vDim, vElement, 'LOCK' ) > 0 );
   CellPutS( vUser, '}ElementProperties_' | vDim, vElement, 'LOCK' );
# EndIf;
# CubeLockOverride( 0 );

# to unlock:
# A simple CellPutS works fine provided we override existing locks
CubeLockOverride( 1 );
If( CubeExists( '}ElementProperties_' | vDim ) > 0 );
   # If( CellIsUpdateable( '}ElementProperties_' | vDim, vElement, 'LOCK' ) > 0 );
      CellPutS( '', '}ElementProperties_' | vDim, vElement, 'LOCK' );
   # EndIf;
EndIf;
# CubeLockOverride( 0 );

# Security access checkbox is not needed
DimensionElementSetLockStatus( vDim, vElement, 1 );

Locking/unlocking a dimension ( this locks/unlocks the entire dimension, no metadata changes are possible )
This does not block data changes in cube cells that reference any of the elements within the dimension, rather, changes to the contents and properties of the dimension

Our options include:
- in Turbo Integrator:
     * DimensionSetLockStatus( <vDim>, <1=lock|0=unlock> ); (this appears to be an undocumented function, it is not recognized in PAW but the process saves and runs)
     * When a chore runs this process, the username in the }DimensionProperties cube becomes 'Admin'
     * CellPutS( <vUser (TM1User() typically) to lock|'' to unlock>, '}DimensionProperties', vDim, 'LOCK' );
- manually, in PAW:
     * right-click a dimension > Lock dimension (if it is currently unlocked) / Unlock dimension (if it is currently locked) (a lock icon will appear when locked)
     * editing the cell in the }DimensionProperties cube on the measure LOCK and the said dimension
- manually, in Architect/Perspectives:
     * right-click a dimension in the Server Explorer > Security > Lock (if it is currently unlocked) / Unlock (if it is currently locked)
     * editing the cell in the }DimensionProperties cube on the measure LOCK and the said dimension
- in the TM1 REST API:
     * POST /api/v1/Dimensions('<vDim>')/tm1.Lock|/api/v1/Dimensions('<vDim>')/tm1.Unlock (204 No Content) (the username in the }DimensionProperties cube becomes the REST API account)

# to test the existence of a dimension lock:
If( Dimix( '}Clients', CellGetS( '}DimensionProperties', vDim, 'LOCK' ) ) > 0 );
   # the dimension is locked
EndIf;

# to lock a dimension:
If( CellIsUpdateable( '}DimensionProperties', vDim, 'LOCK' ) > 0 );
   CellPutS( vUser, '}DimensionProperties', vDim, 'LOCK' );
EndIf;

# to unlock a dimension:
If( CellIsUpdateable( '}DimensionProperties', vDim, 'LOCK' ) > 0 );
   CellPutS( '', '}DimensionProperties', vDim, 'LOCK' );
EndIf;

# Alternatively:
# Security access checkbox is not needed
DimensionSetLockStatus( vDim, 1 );

Hope you found this useful.

All feedback is welcome.