This is a follow-up article on my previous xPorter 2.1 demo. When you build a large and complex project, you end up with tons of user variables in Storyline. Keeping track of what they do, how they’re used, etc. is not easy inside Storyline.
This is where xPorter comes in. This script extracts all your user variables directly from the .story file and then writes them into a Smartsheet. You can then document them in the sheet, share it with your team if necessary, or give it to your client if they’re going to maintain the course.
While you may remember all your variables when you build it, I guarantee, weeks later they look like aliens… Or what happens if someone accidentally renames or deletes a variable? You will never know what the original was.
Installation
To use xPorter you’ll need to set up the following environment once:
- Python 3.x installed on your laptop
- Installing the Smartsheet Python SDK
- Smartsheet account
- xPorter (unzip the downloaded files)
1. How to install Python 3.x?
It depends on your operating system. Here’s a good step-by-step tutorial to install Python: https://realpython.com/installing-python/
In my case, it is Windows and when I run python –version, it shows me the installed version: Python 3.9.0
2. How to install the Smartsheet Python SDK?
Follow the instructions on https://pypi.org/project/smartsheet-python-sdk/ to install the SDK. This library is intended to simplify connecting to the Smartsheet API from Python applications.
I use pip (https://pip.pypa.io/en/stable/) for installing packages for Python.
3. Smartsheet setup
Once you sign up for Smartsheet (you can do the trial version), you can create a sheet for the variables. Name the columns the following (you can always add news ones yourself later):
Name – Text field to hold the name of the variable.
Status – Text field to show the latest status of the field: U (updated), N (new), D (deleted). The script will not remove any variables from the spreadsheet rather sets the status to D if the variable is no longer in the Storyline project. You can decide if you want to remove it or not. This can be helpful if someone accidentally deleted or renamed a variable in storyline.
How to connect Python and Smartsheet?
You will need two things to connect the Python SDK and the smartsheet: an access token (allowing you to connect to the API) and a sheet id (to determine which sheet you’re writing into).
Follow the instructions in this blog to get the ACCESS_TOKEN and sheet id: https://pythonhowtoprogram.com/how-to-read-and-update-smartsheets-with-python-3/.
4. How to use xPorter?
xPorter reads your .story file to extract the user variables. To test it out, create a couple of variables of different types in Storyline.
There are two files you will work with:
- exporter.ini file
- xporter.py Python script
The exporter.ini file holds basic configuration for your script:
[storyline]
filepath = c:workatd21gamedesignsourcestorytest.story
[smartsheet]
access = cpCff2zRe0jzzJnVowrIKDGD3aOxxxxxxxxxx
sheetid = 212488xxxxxxxxxx
The filepath points to the .story file you want to use. The access is the smartsheet access code, and sheetid is the sheet you’re writing the variables to. Setting this .ini file makes sure whenever you run the script the same .story variables will be written to the same sheet.
You can rename the .ini file to xporter_YOURSTORYFILE.ini so you can remember easily. The script will show you any files that match the xporter*.ini pattern. You can keep this file with the source .story.
To run the xporter, just execute the following:
python xporter.py
The script will open a file dialogue to locate the .ini file you want to use.
If the .ini file has both the access token and the sheet id, the rest of the execution is automatic.
If you do not want to include your access token in the .ini for security reasons, keep it blank
access =
In that case you need to supply the access token code when you run the xporter.py Python script:
python xporter.py -a XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Where XXXXXXXXXXXXXXXX is your access token.
xPorter script dependencies
The following packages are needed for the xPorter to run:
import zipfile
import xml.etree.ElementTree as ET
import smartsheet
import sys
import argparse
import sys
from PyQt5.QtWidgets import QApplication, QWidget, QInputDialog, QLineEdit, QFileDialog, QLabel
from PyQt5.QtGui import QIcon
from PyQt5.QtWidgets import QPushButton
import configparser
Some of these are part of the standard Python installation, while others need to be installed manually first. This is a one-time effort to set up the environment to include all dependencies. After that, running the xporter.py script is simply a line of code.
Matthew Bibby
September 12, 2021 8:20 amLegend. Thanks.