The goal of this post is to give users an overview of how to run some of the Python scripts that we have developed. Often, these scripts can be leveraged to do things that Fulcrum does not already have built in. Since Spatial Networks is primarily a Mac shop, this post will focus on doing this on MacOS. (I plan to do a Windows version of this blog in the future.)
Now for the disclaimer: Fulcrum support cannot assist with any issues that you may encounter when getting set up to run, or running, scripts. This is outside the scope of Fulcrum support and you use them at your own risk! If you do run into issues getting anything installed and set up, others have likely run into your issue as well. Searching Google will often yield a thread where a solution can be found.
Lastly, it is important to note that your Fulcrum plan will need to have the developer pack in order to run the scripts. This is because the scripts will be leveraging the Fulcrum API.
Getting set up to use Python
Using the Terminal and getting everything set up is by far the hardest part of running scripts, especially for non-developers, like myself. To start you will need to make sure that you have Xcode and Homebrew installed.
Once you have Xcode and Homebrew installed you can run
brew install python3
to install Python 3 on your computer.
Once you have Python 3 installed you will want to run
brew postinstall python3
This will add Python install package to Python 3 (pip3) so that you can install the fulcrum library in Python 3. Note: Some people have reported that this does not need to be done, but I had to run this.
Now that Python is installed and pip3 will work, we can run
pip3 install fulcrum
to install the Python Fulcrum library to Python 3.
Finally, we are ready to begin running scripts!
The python library repo can be found on our Github page. I am going to focus on the examples that we have contained within the wiki in this repo. The example I am going to use is creating projects from a CSV file.
To start, you will want to copy the example code and paste it into a new file in a code editor (TextEdit, VS Code, Sublime, etc) of your choice. After it has been pasted in, you will want to use the “save as” option and give the file a name with the .py extension. This will save the file as a Python file. Make sure to place the file somewhere easy to find; you will have to navigate to the file’s location in Terminal later.
In the image below, I named the file “add-project.py” and added it to the Documents directory.
Creating the CSV File
Next we will need to create a CSV file that will be used to create the projects. To figure out the structure needed for the CSV file, you can look at the comments in the script we just saved. Below the CSV format line you can see the required format for the file, with the name being the first column and then the description in the second column. The next comment on line 18, you will see a comment about the header row for being skipped. This lets you know that you will want to include a header row in the file.
Now that we know the structure needed for the csv file we can create a file that will be used to create the projects within your Fulcrum plan. In the header rows I have name, description. Below the headers I have the names of the projects and a description for each of the projects. This tends to be less of an issue in Numbers, but be sure to delete any unused columns and rows. In programs like Excel, it can be hard to tell if a row/column is not there or is just empty.
Now, when saving the CSV file, it is recommended (but not required) to save the file in the same directory/folder as the script. This makes it easier when running the script in Terminal.
With the CSV file and Python script created we are almost ready to run our script. But before we can, we will need to obtain an API token from within our Fulcrum plan.
Note that the owner role is the only system role that can access API tokens. If you are using a custom role within your Fulcrum plan, then the role will need to have the permission to “manage API Tokens.” Additionally, the custom role would need to be able to manage projects for this example.
Creating Your API Token
To create your API token log into your Fulcrum user account and then click on the API tab in the navigation pane on the right side of the screen. Then select “Create API Token” button. You will then be asked to give the token a description before the token is generated. Make sure that you save your token somewhere, as this is the only time that the complete token will be visible. If you ever do lose the token, you can delete the API token and generate a new one.
Running the Script
Now that we have the API token we can begin running the script. To start you will want to open up your Terminal and then navigate to the directory/folder that the script and CSV file are located in. In my case, I placed both within the “Documents” directory, so I type
cd Documents
and hit enter. Now that I am in the correct directory we can run the script. To start, we will want to type out “python” and then the name of the script file we want to run. So it should look like this so far:
python add-projects.py
For the rest we will want to reference the script file. Taking a look at the image below we can see on lines 6 and 7 that we will need to add two arguments in order to run the code. For
-t
we need to add the API Token that we just copied. For
-f
we need to add the file name for the CSV file we want to use.
With this information, we can enter in the rest of the details and then run the script. No special characters need to be used, simply add a space then -t followed by another space and then enter the token wrapped with single quotes. Do the same with -f and the name of the CSV file.
The end result should look something like this:
python add-project.py -t ‘YOUR API TOKEN’ -f ‘projects.csv’
Now all you need to do is hit enter to run the script. If it runs successfully, you should see the projects being created in Terminal.
To confirm that the projects were added we can take a look at the projects page in the Fulcrum web app.
Running scripts can be pretty daunting when you are not a programmer, but the most difficult step is getting everything set up. If you can get past the setup hurdles scripts can really add a lot of flexibility and make certain tasks a lot easier by being able to do things that you would not normally be able to do through Fulcrum’s web app. Just make sure to backup as much as possible in the event that you make an error and need to recover!