Adding a MicroStrategy Connection¶

Prerequisites¶

• A user with sufficient permissions is required to establish a connection with MicroStrategy.
• Zeenea traffic flows towards MicroStrategy must be open.

Supported Versions¶

The MicroStrategy connector is available for the SaaS and the on-prem product version.

Installing the Plugin¶

You can download the Microstrategy plugin from Zeenea Connector Downloads.

For more information about how to install a plugin, see Installing and Configuring Connectors as a Plugin.

Declaring the Connection¶

Connectors are created and configured through a dedicated configuration file located in the /connections folder of the relevant scanner. The scanner frequently checks for changes and resynchronizes automatically.

For more information about managing connections, see Managing Connections.

To establish a connection with a MicroStrategy instance, fill in the following parameters in the dedicated configuration file:

User Permissions¶

To collect metadata, the running user's permissions must allow them to access folders and portfolios that need cataloging.

Data Extraction¶

To extract information, the connector runs the following API requests:

• GET /api/searches/results?type=55: To get the list of the dossiers.
• GET /api/projects: To get the name of the dossiers
• GET /api/v2/dossiers/[dossier-id]/definition : To get metadata from each dossier
• GET /api/documents/[dossier-id]/cubes : To get the list of the cubes linked to a dossier
• GET /api/v2/cubes/[cube-id] : To get cube metadata (attributes and metrics)
• GET /api/object/[dossier-id]?type=55: To retrieve the file definition and extract metadata (creation date, last modification date, owner ID, certification status, category).
• GET /api/users/[user-id]: To retrieve the owner's name in metadata, and if this email exists, create a contact.
• GET /api/model/metrics/[metric-id]: To retrieve the associated formula.

Collected Metadata¶

Inventory¶

Will collect the list of portfolios accessible by the user.

Lineage¶

The connector is able to reconstruct the lineage of tables used in the folders if they are present in the catalog. This feature is available when MicroStrategy uses datasets from the technologies mentioned below. In this case, it is necessary to specify an additional parameter in the original connections of these tables as referenced in the MicroStrategy connection configuration.

The following API calls are made to obtain the lineage information:

• GET /api/model/attributes/[attribute-id]: Allows you to retrieve the id of the table where this attribute is attached.
• GET /api/model/datasources/[source-system-id]: Allows you to retrieve the ID of the connection that is associated with it.
• GET /api/model/connections/[connection-id]: Allows to build the connection code for the Zeenea lineage.

Visualization¶

A visualization object is a MicroStrategy portfolio.

• Name
• Source Description

• Technical Data:

  • Project Id
  • Project Name
  • Dossier Id
  • Dossier Name
  • Link To The Dossier
  • Certified
  • Creation Date
  • Last Modification Date
  • Dossier Category
  • Owner

Dataset¶

A dataset is a table used in a visualization object.

• Name
• Source Description

• Technical Data:

  • Dataset Id
  • Dataset Name

Field¶

A field can be an attribute, a metric, or a field from the dataset.

• Name
• Source Description: Formula if available (Available only in MicroStrategy version 2021 update 7 and later. Modeling service must be configured and enabled on the machine).
• Type
• Can be null: Not supported. Default value false.
• Multivalued: nNot supported. Default value false.
• Primary Key: Not supported. Default value false.

• Technical Data:

  • Technical name
  • Native type
  • Type: can be attribute, metric, or attribute form
  • dataType
  • baseFormCategory
  • baseFormType

Object Identification Keys¶

Each object in the catalog is associated with a unique identifier key. When the object is imported from an external system, the key is generated and provided by the connector.

For more information about identifier keys, see Identification Keys.

Additional Information¶

The connector is able to retrieve portfolios from MicroStrategy, including, under certain conditions, those with a "prompt". (NOTE: hereafter, we use the term "prompt" also used in MicroStrategy's English literature).

The prompts can be of one of the following types:

• UNSUPPORTED, VALUE, ELEMENTS, EXPRESSION, OBJECTS, LEVEL.

The possible types of values for the "VALUE" prompts are :

• TEXT, NUMERIC, DATE.

Because a MicroStrategy portfolio with a prompt must be accessed with values requested by the prompt in order to be analyzed, they can only be retrieved by the Connector under the following conditions:

• The prompt is not mandatory
• OR the prompt has a predefined response field,
• OR the prompt has a default value,
• OR the prompt is of type VALUE or ELEMENTS.

The Connector will therefore try to guess possible values for the expected elements to reach the portfolio definition since the MicroStrategy API requires it to return the portfolio metadata.

Configure the response of a prompt¶

When the prompt autocomplete mechanism is not sufficient, it is possible to configure a response value.

Setting¶

To do this, you must fill in the inventory.prompt_answers parameter. This parameter can contain either a content in JSON format or a URL (file: protocol) to the local JSON file.

When there is only one value to fill, it can be convenient to put the content directly in the configuration file. In this case, it is useful to use a multiline string that starts and ends with three quotes ("""). The use of an external file will quickly become advantageous as soon as the number of responses increases. Moreover, the modifications in the external file are taken into account without having to restart the scanner.

Example of configuration¶

With external file:

inventory {
    # Semicolon separated list of folder paths. '\' or '/' can be used interchangeably.
    #root_folder_list = 
    #fetch_page_size = 1000

    prompt_answers = "file:///opt/zeenea-scanner/connections/prompt_answers.json"
}

With an internal value:

inventory {
    # Semicolon separated list of folder paths. '\' or '/' can be used interchangeably.
    #root_folder_list = 
    #fetch_page_size = 1000

    prompt_answers = """
        [ 
            { 
                "id": "FDC7791206C4BA721D6A0A55AC600BCC",
                "type" : "ELEMENTS",
                "answers" : [
                    {
                        "id": "hVALUE;39CFA940E411A7A6CB8D1052EB41BF71",
                        "name": "VALUE"
                    }
                ]
            },
            {
                "key": "9EC55F9D44B19BB0B960BEB97341C520@0@10",
                "name": "Select a Time Period",
                "type": "EXPRESSION",
                "answers": {
                    "content": "Month = Sep 2010",
                    "expression": {
                        "operator": "And",
                        "operands": [
                            {
                                "operator": "In",
                                "operands": [
                                    {
                                        "type": "attribute",
                                        "id": "8D679D4411D3E4981000E787EC6DE8A4",
                                        "name": "Month"
                                    },
                                    {
                                        "type": "elements",
                                        "elements": [
                                            {
                                                "id": "8D679D4411D3E4981000E787EC6DE8A4:201009",
                                                "name": "Sep 2010"
                                            }
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
                }
            }
        ]
    """
}

JSON format of responses¶

JSON is an array of objects that represent a prompt with its response.

Each object contains:

• a type field that indicates the type of prompt as provided by the API description of the prompt GET {{baseUrl}}/api/documents/{{folderId}}/instances/{instanceFolder}}/prompts
• at least one identification field: key, id, or name
• an answers field

The format of the answers field depends on the type of the prompt and has many variants. It is not interpreted by Zeenea and passed as is to the PUT {{baseUrl}}/api/documents/{{folderId}}/instances/{instanceFolder}}/prompts/answers response API.

See the MicroStrategy documentation for details of this format.

When the connector needs to respond to a prompt, before using the default value or calculating a possible response, it checks to see if any response in the list matches the prompt to be processed.

A response matches a prompt, if:

• they have the same type,
• they have the same VALUE type, they have the same data type,
• one of the fields key, id, name are equal

If several entries match, the one with the same key has priority, then the one with the same id, and finally the one with the same name.