/
Processes

Processes

Owned by Ada
Last updated: Aug 28, 2023
15 min read

All processes included in the Apliqo UX ContentStore are control objects prefixed with curly brace "}". If the ContentStore is browsed without the "display control objects" option selected then the ContentStore will appear as if empty. This is by design.

All processes in the ContentStore are prefixed with "}APQ.UX" except for a handful of }bedrock processes taken from the open source Bedrock 4 library. The ContentStore is made up of a relatively small and easy to manage number of objects.

It is possible to run the ContentStore inside another TM1 instance such as an instance being reported on via the UX. In theory adopting such a setup where only a single TM1 instance is the source for the reporting or planning application would remove the requirement to sync users and metadata between the instance and ContentStore, simplifying the overall setup. However, this setup is nevertheless not recommended for the following reasons:

  1. Upgradeability; having ContentStore objects inside another instance will make upgrading more difficult and unable to be automated (for example when the upgrade installer automatically shuts down the ContentStore service and replaces objects).

  2. Backups; having the ContentStore objects inside another instance means backups will be orders of magnitude larger and should not be managed by the ContentStore's automated process

It is still possible to run the ContentStore in such a configuration. However, it is not officially supported and you do so at your own risk.

ContentStore Server Management

The following processes perform "ContentStore database level" management functions and should only be run by a ContentStore administrator.

» }APQ.UX.Server.Backup

This process takes an at rest file system backup of the ContentStore instance to the backup location defined in the }APQ Settings cube.

This process is scheduled as the APQ.ContentStore.Backup chore which should be scheduled daily.

Note: this process has a dependency on 7-zip (7z.exe). 7-zip is not included in the Apliqo UX installation. This utility is however already available on most servers and can be downloaded from Download The 7-zip executable is portable and does not require installation and Windows registry changes. 7z.exe needs only to be available to the ContentStore and the location of the executable to be correctly mapped in the }APQ Settings cube.

» }APQ.UX.Server.Clean

This process is extremely dangerous and should only be used:

  • For the intended purpose

  • If you know what you are doing

  • If the backup process is working and tested

This database management process provides various options to clear (i.e. delete) various metadata (and thereby data) from the ContentStore. Once executed there is no going back (except for restore via backup).

The intended use case for this process is to assist with creating new ContentStore instances from copies of existing ContentStore databases.

Various parameters are provided to alter the scope of what is cleared. For example:

  • Clear entire ContentStore (i.e. reinitialize empty ContentStore with "factory settings")

  • Clear apps (with options to selectively skip admin apps and protected apps or delete all)

  • Clear metadata of synced instances

  • Clear code snippets

  • Clear security (i.e. delete all users and groups, except for built-in groups)

This process should only ever be run when setting up a new ContentStore buy using an existing ContentStore instance as a "template".

» }APQ.UX.Server.Maintenance

This is scheduled as the APQ.UX.Server.Maintenance chore which should be scheduled daily. Ideally the timing would be at the very end of any overnight maintenance window just prior to the start of daily operations. This process calls other processes which perform various internal functions such as:

  • maintaining relative time reporting consolidations & subsets

  • maintaining internal PickList subsets

  • maintaining and updating object security and app element security

» }APQ.UX.Server.Settings.Export

This process exports the content of the ContentStore to file in the export path location specified in }APQ Settings. This can be used during transport/migration between environments as part of a D->Q->P process, or can be used during software upgrade to shift UX applications from one ContentStore to another, particularly in cases where several software versions are being jumped over.

The process contains parameters for individually exporting different kinds of ContentStore content:

  • Security Model

  • Apps

  • Code Snippets

  • Instance Metadata

  • User Settings

... although in most use cases all content type would be exported.

» }APQ.UX.Server.Settings.Import

This process imports files from the defined source data path location specified in }APQ

Settings. This can be used during transport/migration between environments as part of a D-

>Q->P process, or can be used during software upgrade to shift UX applications from one ContentStore to another, particularly in cases where several software versions are being jumped over.

The process contains parameters for individually importing different kinds of ContentStore content:

  • Security Model

  • Apps

  • Code Snippets

  • Instance Metadata

  • User Settings

... although in most use cases all content type would be exported.

The process also contains an option to change instance names during the import process. This can be useful in a D->Q->P system where instance names indicate the environment.

» }APQ.UX.Server.Server.Settings.Dim.Export

This process is a helper process which performs work on behalf of

}APQ.UX.Server.Server.Settings.Export to export a dimension definition to file. The file format is proprietary to Apliqo UX.

There should never be a need to run this process directly passing in a dimension name as a parameter.

(However, this process can also do no harm since all it does is export metadata to text file).

» }APQ.UX.Server.Server.Settings.Dim.Import

This process is a helper process which performs work on behalf of

}APQ.UX.Server.Server.Settings.Import to load a dimension definition (including hierarchy & attribute definitions) from a saved file. The file format is proprietary to Apliqo UX.

» }APQ.UX.Server.Metadata.Export

This process exports all "static" ContentStore internal dimensions as TurboIntegrator script instructions. It is used internally by Apliqo developers for preparing the }APQ.UX.Server.Upgrade process during release preparation.

There should never be a need to run this process in the context of a customer implementation.

(However, this process can also do no harm since all it does is export metadata to text file).

It is perfectly safe to delete this process.

» }APQ.UX.Server.Upgrade

This process ensures that all required "static" internal ContentStore dimensions exist and contain all required attributes.

The process is included in each upgrade package and should be executed at the end of an upgrade. If using manual loose file upgrade then execute manually once and once only. (If upgrading with a Pulse online package this process is executed automatically).

After it has been run once it is perfectly safe to delete this process.

Apps

The real content store within the ContentStore is the attribute cube of the }APQ UX App dimension. The structure of the application is mirrored in the structure of the UX App dimension and the definition of every screen in Apliqo UX is stored in the attributes of the dimension. In fact the real "content store" is the }ElementAttributes_}APQ UX App cube. Everything else in the content store instance is really just for management purposes.

The set of processes in this section are dedicated to this central business of the ContentStore; managing the screens or "apps" and the properties stored against each app. From a technical perspective this comes down to managing the }APQ UX App dimension, adding and deleting elements and settning attribute values.

» Managing Apps

This group of processes are for exporting apps out of one ContentStore instance and importing into another instance. This can be used for example in the context of creating a migration package to promote a set of screens from dev/test to production for example.

The job performed by each process should be rather self explanatory from the name of each process.

  • }APQ.UX.Dim.App.Export

  • }APQ.UX.Dim.App.Export.All

  • }APQ.UX.Dim.App.Import

  • }APQ.UX.Dim.App.Import.All

In the standard "out-of-the-box" security configuration that ships with the ContentStore only members of the "APQ Admin" group have access to export and import apps. If you want to allow report builders (power users) to also have access to this functionality then all you need to do is give the "APQ PUser" group read level access to the export and import processes.

Note: that no UI (as of v2.5) in Apliqo UX is provided to export and import apps. To perform these functions administrators need to use an admin GUI such as Arc or PAW.

Read more on this topic in Apps export & import article.

» The App Mart

• }APQ.UX.Dim.App.Download

This process is part of the "Apliqo App Mart" application which will ultimately allow

administrators to download content from the cloud to their application. This feature is currently in prototype stage and this process is currently not fully functional.

» Working with Public Apps

Members of the group "APQ PUser" have the ability to create / edit / delete apps to which they have been granted at least WRITE access. The following set of processes facilitate the editing of apps behind the scenes. All members of the "APQ PUser" group.

  • }APQ.UX.Dim.App.Create

  • }APQ.UX.Dim.App.Create.Root

  • }APQ.UX.Dim.App.Delete

  • }APQ.UX.Dim.App.Duplicate

  • }APQ.UX.Dim.App.Duplicate.Root

  • }APQ.UX.Dim.App.Move

  • }APQ.UX.Dim.App.EditMode.Toggle

  • }APQ.UX.Dim.App.Restore

Note: that there should not EVER be a need to actually call any of these processes directly via an admin interface. The "app management" app and standard "edit mode" functionality already provide a controlled GUI whereby these processes are called in the background but the users are unaware and need not be aware that these processes are doing the work in the background while they are editing public apps.

The job performed by each process should be more or less self explanatory from the name of each process, e.g. create/delete/duplicate/move. The "root" processes act at root application level and require a separate process due to the requirement to set security for new objects which don't have a parent to inherit existing rights from.

The "EditMode.Toggle" process is used internally to set status flags on app objects in order for the front end to distinguish whether an object is published versus in draft status and only visible in edit mode.

» Working with Private Apps

Members of the group "APQ User" only have the ability to create / edit / delete private apps. The following set of processes facilitate the editing of private apps behind the scenes.

  • }APQ.UX.Dim.App.Create.Private

  • }APQ.UX.Dim.App.Delete.Private

  • }APQ.UX.Dim.App.Duplicate.Private

  • }APQ.UX.Dim.App.Move.Private

Note that each of the above processes is actually nothing but a wrapper which calls the worker process of the same name (but without the ".private" suffix) with a parameter to indicate to act on a private app not a public app. From a security model perspective normal "consumer" users only have access to the private processes and so are only able to create private apps even if they were to log onto the ContentStore via another GUI than UX.

Note: that as for the processes for public app maintenance there should NEVER be a need to actually call any of these processes directly via an admin interface. The "app management" app and standard "edit mode" functionality already provide a controlled GUI whereby these processes are called in the background but the users are unaware and need not be aware that these processes are doing the work in the background while they are editing private apps.

» App Utilities

The following group of processes perform "utility" functions related to the management of apps. As the purpose of these processes can vary somewhat, some explanation is provided in the section below as to what each process does.

}APQ.UX.Dim.App.Import.ReportingLeaf.Add

To support the new activity logging feature introduced in v2.5 the structure of the }APQ UX App dimension was adjusted to include a leaf child of each view and dashboard level (that is what constitutes a "screen" in Apliqo UX) as these nodes are consolidations the leaf element is required as a proxy element to hold numeric data against in a TM1 cube.

From v2.4 and above the leaf element is automatically created whenever a new view or dashboard is created. This process ensures that if importing an application from an older version that the required leaf elements are created.

}APQ.UX.Dim.App.JSON.RemoveBlanks

Most attributes of the }APQ UX App dimension are saved as JSON strings. However, as null or an empty string can be interpreted as invalid JSON this process scans the dimension to replace any empty strings with "{}" (valid empty JSON).

}APQ.UX.Dim.App.ReplaceAppReference

In Apliqo UX it is possible to set up a "drill" navigation on right-click from one screen to another, or to navigate via hyperlink or navigation widget. If an screen of moved to another location this process acts as a find/replace utility to find and replace instances of the old application ID with the new application ID within a defined scope of an existing application.

Should navigation links break as the result of moving an application, this process can be used to mend the links.

}APQ.UX.Dim.App.ReplaceDimReference

If a cube is redesigned and dimensions are swapped or a helper dimensions are added or replaced, this process acts as a find/replace utility to find and replace instances of the old dimension ID with the new dimension ID within a defined scope of an existing application.

}APQ.UX.Dim.App.ReplaceInstanceReference

If the same application exists on multiple instances this process can be used to change the reference from one instance to another on the fly. This avoids the need to duplicate screens within a Apliqo UX application. Rather the same application can be used and dynamically pointed to different target instances. This can ha especially useful for admin apps which leverage common structures and requirements such as setting security.

Should an instance name be changed in the instances.json file then this process can also be used to make wholesale find/replace changes throughout the whole ContentStore.

}APQ.UX.Cub.SettingsServiceDimensions.Update.FromViewDef

In the }APQ UX Dimension dimension the list of dimensions existing in each connected instance is maintained. This is generally maintained using the metadata syncing service. This process provides an alternate means of maintaining the list of dimensions per instance where a default member value is set on initial login for users to set the point of view context for dimensions in the Apliqo UX FilterBar.

The process scans the viewDef and settings JSON objects for a defined application branch of }APQ UX App (or all apps) for both cubes and dimensions that have been used to define views in Apliqo UX and add these as elements to the relevant instance hierarchies in the }APQ UX Cube and }APQ UX Dimension dimensions.

}APQ.UX.Cub.ViewDefinitionDefaults.Update

This is a utility process used to update the }APQ UX ViewDefinition Defaults cube with the view definition of the currently selected app. When creating apps if a default layout is predefined for a cube then this makes the new widget immediately useable on creation (as opposed to needing to drag all red undefined dimensions to a correct layout position).

Note: currently there is no UI provided to set the default view definition (this feature is coming!) and this process needs to be executed manually passing in the ID of the relevant app which shoudl be used as the default layout for the given object type.

}APQ.UX.Dim.AppSubType.Create

This is a utility process is used when creating new widget types. For example if you are creating a custom widget in your application then you would use this process to insert the new widget type into the }APQ UX AppSubType dimension and give it a display caption. Only after the widget type is inserted into the correct location in this dimension will it be available to be used by report developers when developing UX applications.

The widgets PickList drives the available widget type selection in the application management app.

}APQ.UX.Dim.AppSubType.Update.PickLists

This is a utility process which creates and maintains the PickLists in the }APQ UX AppSubType dimension which are used internally within the application management app. This process is called by the daily maintenance chore.

Code Snippets

Apliqo UX applications can contain custom html documents and custom javascript functions. These are stored in the custom folder of the web app. The Content Store can also store code snippets which can be used in your application. This allows for migration of apps including custom components without needing to copy any files to the webserver.

Presently only custom html is supported. However ultimately all kinds of code snippets that you may need in your UX application will be able to be stored in the Content Store (javascript, MDX, python, etc.)

» Snippet Utilities

The following group of processes perform "utility" functions related to the management of snippets.

}APQ.UX.Dim.Snippet.Create

This process is called in the background via the UI when managing creation of snippets or folders / sub-folders for managing snippets.

}APQ.UX.Dim.Snippet.Delete

This process is called in the background via the UI when managing deletion of snippets or folders / sub-folders for managing snippets.

}APQ.UX.Dim.Snippet.Move

This process is used to move a snippet from one folder to another.

}APQ.UX.Dim.Snippet.Export

This process exports a snippet (or a folder, or a branch, or the whole snippet dimension) to file. This process is also used internally by the Dim.App.Export process to ensure that snippet dependencies are exported with the apps that they belong to.

}APQ.UX.Dim.Snippet.Import

This process imports a snippet (or a folder, or a branch, or the whole snippet dimension) to file. This process is also used internally by the Dim.App.Impotz process to ensure that snippet dependencies are imported with the apps that they belong to.

}APQ.UX.Dim.Snippet.ReplaceTextReference

This is a utility process to perform find/replace operations in the snippet dimension. The find/ replace is valid for the Name, Caption and Description fields.

Note:

The find/replace cannot be used for the code itself as the code is stored as a bitwise string (in order to avoid issues with carriage returns and special characters) and so is not human readable.

Security Management

The ContentStore comes with its own set of cubes and processes to internally manage security.

Object security is preset or "OOTB" with preconfigured access for the roles of end user (APQ User), report author (APQ PUser) and ContentStore administrator (APQ Admin). However, element security on the }APQ UX App dimension is very much application specific and so has a dedicated application to manage it. The following processes are either directly involved in managing app security or perform utility functions such as importing or exporting of users/ groups.

» }APQ.UX.Security.AssignClientGroups

This process reads data from the }APQ UX Security Manage Client Groups cube where group memberships are assigned, and applies the settings to the ContentStore security model. This process is included in the daily maintenance chore.

» }APQ.UX.Security.AssociateCAMIDToGroup

In case your TM1 reporting model and ContentStore are using CAM for authentication and group memberships are managed in CAM (or in CAM's ultimate source such as LDAP) then this process can be used to associate a ContentStore built-in group (such as APQ PUser or APQ Admin) with a CAM group. Members of the CAM group will automatically become members of the associated group on login and inherit the permissions associated with the non-CAM group.

Note: as this is an administrative function and moreover a "once off" action there is no UI provided for this process. It should be executed manually via Arc or PAW.

» }APQ.UX.Security.ClientGroups.Import.FromInstances

This process is the interlink between the metadata syncing service and the ContentStore security model. The process reads from the instance metadata repository cubes and adds all users, groups (and group memberships) which have been marked to be imported into the ContentStore.

There is no need to maintain users and groups separately in the ContentStore. By design Apliqo UX allows you to sync or inherit users, groups and memberships from your existing TM1 instances.

» }APQ.UX.Security.ClientGroups.ImportExport

This process provides an alternate (manual) mechanism to import or export clients, groups and group memberships between other instances and the ContentStore versus using the metadata syncing service. The process uses a standard CSV file format to import/export security metadata

Note: as this is an administrative function and moreover a "once off" action there is no UI provided for this process. It should be executed manually via Arc or PAW.

» }APQ.UX.Security.Dim.App.LoadAccessRights

This process reads from the }APQ UX App Security Access cube and applies element security to the }APQ UX App dimension. This is a mission critical function and is included in the daily maintenance chore.

» }APQ.UX.Security.Manual.Client.Create

This process allows an authorized ContentStore administrator to manually create a new ContentStore user.

This process is provided for completeness to allow manual setup for simple applications. In normal use cases we strongly recommend automating ContentStore user creation and security maintenance by using the metadata syncing service.

Note: Creating a ContentStore user allows the user to log in to Apliqo UX. The user must also exist on the reporting instance(s) in order to be able to browse data in the application.

» }APQ.UX.Security.Manual.Group.Create

This process allows an authorized ContentStore administrator to manually create a new ContentStore security group.

This process is provided for completeness to allow manual setup for simple applications. In normal use cases we strongly recommend automating ContentStore user creation and security maintenance by using the metadata syncing service.

UX Toolkit

The "UX Toolkit" is a python executable which assists in server maintenance, especially the metadata syncing service. The utility is a command line executable. The toolkit processes provide a wrapper which allows the utility to easily be executed via TI process and from the UX interface.

The utility principally manages the exchange of metadata between "reporting instances" (as set in the instances.json file) and the UX contentStore. The executable runs in 4 modes:

  1. store : writes to the settings.json file which stores control parameters for the executable

  2. transfer : transfers metadata from reporting instances to the contentStore

  3. createattrs : creates attributes in reporting instances which have special functions in Apliqo UX

  4. clean : cleans redundant objects from reporting instances from UX 1.x versions (i.e. precontentStore objects)

Each mode has a separate TI wrapper process to make calling the utility easier to manage and configure. Via naming convention it is obvious which process calls which mode.

  • }APQ.UX.Toolkit.Run.Store

  • }APQ.UX.Toolkit.Run.Transfer

  • }APQ.UX.Toolkit.Run.CreateAttrs

  • }APQ.UX.Toolkit.Run.Clean

Other

The following processes perform other functions used for management of the ContentStore.

» }APQ.UX.Cub.ConnectionAnalysis.Update

This process reads from the }APQ UX Connection Log cube and writes data to the }APQ UX Connection Analysis cube. The connection log is written to when users log in to Apliqo UX and captures as text measures the OS, device type, browser and screen resolution of the user's session. This process takes the string measures and transforms to multi-dimensional data be maintaining dimensions for browser, device, OS, screen size. The connection analysis cube can then be used by administrators to analyse usage of their Apliqo UX application.

» }APQ.UX.Dim.Snippet.X

The code snippet feature was introduced in v2.5 with support for html snippets. Future support is planned for additional code types (e.g. CSS, javascript, MDX, TI, Python).

}APQ.UX.Dim.Snippet.Create

This process creates a new code snippet (or folder) in the }APQ UX Snippet dimension.

}APQ.UX.Dim.Snippet.Delete

This process deletes a code snippet (or entire folder and all descendants) from the }APQ UX Snippet dimension.

}APQ.UX.Dim.Snippet.Move

This process moves a snippet (or folder) in the }APQ UX Snippet dimension from one location to another.

}APQ.UX.Dim.Snippet.ReplaceTextReference

This process is a generic find/replace function for strings within code snippets.

Bedrock Utilities

The following Bedrock 4 library processes are included in the Apliqo UX ContentStore. They are used internally by the }APQ.UX processes to perform basic tasks. If you would like further information on the functions of any of the bedrock processes links are provided to the documentation on the bedrock site.

Related content