Upgrading InVision 1.0 to 2.0 and beyond

by

With InVision 2.0, we’ve also created a tool for upgrading the system model (model schema and solution metadata) from one version to the next.  The Model Version Tool (MVT for short), enables you to incrementally upgrade the system model from its current version to any version supported by the tool (no, you can’t downgrade after an upgrade).

Version 1 of MVT is executed from the command line using the following command syntax:

mvt /connection "[connection string]" /[upgrade option] /[config options]

// For example
mvt /connection "Data Source=sql01prod;Initial Catalog=pbInVision_Hypotesia;Integrated Security=True;" /upgrade-full

Command switches

  • /connection – Specifies the connection string to the InVision Solution database to upgrade.
    Example : mvt /connection “Data Source=local;Initial Catalog=pbInVision_X;Integrated Security=True;”
  • /output – Optional. Specifies the name of the file that the process writes the upgrade summary to. If not specified, the output is written to “mvtresult.json”. The file is overwritten, not appended to.
    Example : /output hypotesia_upgrade.txt.
  • /defaults – Optional. Specifies the name of the file containing (default) custom upgrade definitions. The file format is described in the Custom Upgrade Definitions section below.Example :/defaults defaults.json
  • /upgrade-full – Specifies that you want to upgrade both the model schema and content to the next version.
  • /upgrade-model – Specifies that you want to upgrade only the model schema to the next version. (You’ll need to upgrade the content eventually, but you may want run content verification first to create Custom Upgrade Definitions)
  • /verify-content – Verifies that the content of the Solution (database) is valid for the current model version. The result is written to the output file.
  • /from-version – Can only be used together with the /verify-content switch. Use this switch when you’re upgrading over several version steps, for example from 1.0.0 to 2.1.0
  • /upgrade-content – Upgrades the content to the current model version.
  • /version – Ouputs the current version of the model to the console.

Custom Upgrade Definitions

Custom Upgrade Definitions are used for specifying custom rules for upgrading Solution content from one version to the next, or the current model version. Custom Upgrade Definitions can be specified in a file with a JSON format.

For example, if you have some formula, for example @P01[] = @P02[] + @P03[], which is used in a lot of places in your Solution, and you want to replace that formula with something else, you need to add that as a custom upgrade definition.

The example below shows the structure of a Custom Upgrade Definition file containing the JSON definition for two custom rules converting from v1 row styling expressions to v2 row styling expressions.

[
  {
    "FromExpression": "@#row[LineType:#StartsWith(SumLine)#]=SumLine;",
    "ToExpression": "SETROWSTYLE(STARTSWITH(LineType, "SumLine"), "SumLine");",
    "RuleType": null
  },
  {
    "FromExpression": "@#row[LineType:#StartsWith(TotalSum)#]=TotalSum;",
    "ToExpression": "SETROWSTYLE(STARTSWITH(LineType, "TotalSum"), "TotalSum");",
    "RuleType": null
  }  
]

So, the structure of a Custom Upgrade Definition file is

[
    {
        "FromExpression":"from-expression1",
        "ToExpression":"to-expression1",
        "RuleType":"ruleType" or null 
    },
    {
        "FromExpression":"from-expression2",
        "ToExpression":"to-expression2",
        "RuleType":"ruleType" or null 
    }
]

The Role of the RuleType property

The RuleType property is used by the upgrade tool to select which Custom Upgrade Definitions to apply when upgrading different components of a Solution.

The RuleType property can be set to one of the following values:

  • “DataGridRowStyle”
  • “DataGridFormula”
  • “DataGridDataRule”
  • “WorkbookInteractionExpression”
  • null

If you want the rule to apply to any component upgrade, set RuleType to null.

Whaaat? I’m totally confused…just show me what to do!

Do you need all those switches? Can’t you just simply upgrade and fudget about it? Yes, when upgrading between most versions, you can just run /upgrade-full. However, since 1.0 to 2.0 is a major upgrade (going from Silverlight to HTML, including the introduction of Eaze), there’s some stuff we’re not able to automatically upgrade for you.

Here’s the recommended approach for upgrading InVision 1.0 to 2.0.

  1. Back up the Solution database
  2. Open the command prompt in the Model Version Tool folder
  3. Upgrade the model by running:mvt /connection “DataSource=sqlserver;Initial Catalog=solution_db;Integrated Security=True;” /upgrade-model.
    Running this command upgrades the model to version 2.0.0
  4. Analyse the content validity by runningmvt /connection “Data Source=sqlserver;Initial Catalog=solution_db;Integrated Security=True;” /verify-content /from-version 1.0.0 /defaults defaults.json.
    In the MVT folder, open mvtresult.json and examine the content of the file. The file may contain a number of issues. The issues listed in the file describe what cannot be upgraded either automatically or based on Custom Upgrade Definitions, or things you should check manually because we cannot verify that we got it completely right (even though the syntax is valid, the semantics may not be valid). Based on this information, add Custom Upgrade Definitions to the defaults.json file.
  5. Rerun the command from the previous file and add Custom Upgrade Definitions until you are satisfied. If you have been using the @InvokeActionGroup or @SendMessage commands, you won’t be able to add Custom Upgrade Definitions for them. If you get rid of all messages except for those, you’ve come as far as you can using the tool.
  6. When you’re satisfied, runmvt /connection “Data Source=sqlserver;Initial Catalog=solution_db;Integrated Security=True;” /upgrade-content /defaults defaults.jsonThis command will upgrade the content to the current version of the model.
  7. Open the Solution and the Workbooks and verify that everything works.
  8. If your Solution have any charts, you need to rebuild those manually.
  9. Since we’ve moved from Silverlight to HTML, you need to edit your Workbooks and adjust the layout so it looks good on the new platform.

Where can I get it?

You can download the tool internally from \pbsndfileInstallsD – SoftwareProfitBaseProfitbase InVision2.0Tools

– The InVision Team