Using the File Upload API to automate documentation runs

In addition to being able to generate documentation manually based on a QUBEdocs Package, QUBEdocs Cloud allows users to upload a QUBEdocs Package over HTTPS by using the QUBEdocs API. This is useful for integrating an on-premise version of Planning Analytics/TM1 with QUBEdocs Cloud or integrating QUBEdocs Cloud with another third party application. 

IMPORTANT Before using the API you will need to create a chore to automatically schedule the "}QUBEdocs Update" process to run at least 10 minutes before the API call is invoked.  This will ensure that information sourced from the TM1 Server such as object definitions, stats, cube & dimension relationships etc. are written to disk. The chore can be set with the following properties.

Steps on how to use and test the API are given below.

First, you need to generate an API token for your connection:

1. Edit the model connection by navigating to the 'Edit Settings' menu option
   
2. Click the 'API' tab
3. Create a unique token for the connection by clicking the '+ Create token' button. This will add the new entry to the table below the button. From here you can see when it was created, the value for the token itself and whether or not it is active or has been expired.

Navigate to the QUBEdocsFiles folder within your TM1 model. If Upload.ps1 does not exist, click on the 'Download Sample Script' button. This will download a PowerShell script. Place it into the QUBEdocsFiles folder within your TM1 model.

Method 1: Using PowerShell and Windows Task Scheduler

1. Launch a Windows PowerShell window, navigate to where Upload.ps1 is located and execute the PowerShell script with the following parameters:
   ./Upload.ps1 "{API Key}" "{Your Name}" "{Path to TM1 Data Directory}"
   
2. If it is successful you will see the message:
   
3. After running the command check that you can now see the new documentation version generated / being generating in QUBEdocs Cloud.
4. If regular scheduled uploads are required a Windows Scheduled Task can be setup to send the documentation through the API daily or weekly. 

Method 2: Using a TM1 Chore

1. Open Architect and navigate to the process "QUBEdocs Create Package".
2. To test: Under the Advanced -> Parameter tab, paste the unique API token key from the QUBEdocs Cloud connection into the pDestFolder "Default Value" placeholder. If your tm1s.cfg file is located in a different place to your model, you can specify its location in the pTM1s "Default Value" placeholder. Manually run the QUBEdocs Create Package process in TM1 and verify that this triggered documentation generation on your QUBEdocs Cloud connection.
3. You can then setup a chore to call QUBEdocs Create Package as often as you'd like to generate documentation. Specify the parameter values as was done in the previous step.
   
   

Troubleshooting: 

In the Prolog of the QUBEdocs Create Package process, change the following line EXECUTECOMMAND(sExecuteStr,0); to EXECUTECOMMAND(sExecuteStr,1); and re run the process.

Next open Powershell and navigate to your data directory.

Copy the command from QUBEdocsExecuteStr.txt excluding the "" and run it in Powershell. This should give you some idea as to what the issues are.

The most common ones are:

1. Your group policy is blocking execution of PowerShell scripts.
2. The directories you've selected are incorrect.
3. The token is incorrect or you've forgotten to put quotes around it.
4. Parameter values were not correctly specified in the chore for QUBEdocs Create Package.
5. Try running the following command on the PowerShell script Unblock-File Upload.ps1
6. Post security updates for Windows and PowerShell, TLS 1.2 and TLS 1.3 get disabled. To re-enable, run the following two commands in PowerShell:

   Set-ItemProperty -Path 'HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NetFramework\v4.0.30319' -Name 'SchUseStrongCrypto' -Value '1' -Type DWord

   Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\.NetFramework\v4.0.30319' -Name 'SchUseStrongCrypto' -Value '1' -Type DWord

   Restart PowerShell and try running the script again.