Creating an iOS Shortcut

Automation is an important feature in any (advanced) notes app. We built Portway to play well with others through the use of content APIs.

Siri, save this van spot

When I am on a trip I like to log certain locations to a note. I have a "Places" project in Portway, with a document for each town. When friends are traveling, I like to dig up my notes on where they're going and send them anything I've found that they may like such as a coffee shop or camping spot. One note I have is dedicated to "van spots". These are sweet dispersed camping spots I've found as I drive or motorcycle around. I wanted to automate recording the location of these van spots, but until we release the native Portway app for iOS, I'm not able to do that... But wait, iOS shortcuts!

Shortcuts

If you’re not familiar, Shortcuts is an app on iOS purchased by Apple. Apple beefed up this app by adding Siri integration and more a couple years back. You can use Shortcuts to automate tasks like recording a transaction in your favorite budget app when entering your favorite coffee shop (I use YNAB), or playing a certain playlist in your favorite podcast player (I like Overcast). MacStories has an insane amount of shortcuts for you to check out.

The task: Append my current location to a Portway document called "Van spots" when I say “Siri, save my location in Portway” Note: This may seem like a lot of steps, but you only have to do it one time. Once the shortcut is set up, you can tell Siri to run the shortcut whenever you say “Siri, save my location in Portway” and it‘s as simple as that!

Let’s get started

First, you‘ll need a Portway project and document you want to post to from your phone. You can create a new project, or use an existing one. Next, you’ll need to create a project key. A project key gives some one or some thing access to your project’s content. This can be read, write, or admin access (be careful).

  1. Create or use an existing project
  2. Create or use an existing document, and write down the document ID
    • The document ID is in the URL when looking at the document /d/projects/<PROJECT_ID>/document/<DOCUMENT_ID>
  3. Go to the project’s settings, and select “API Keys”
  4. Click the big, green “Add project key” button
  5. Give this key the name “iOS Shortcuts” or something obvious to you
  6. Give this key the “Contributor” role
align-right

Create a shortcut

You now have a read-only key to read the documents in your project. We’re going to copy this key to the clipboard, and use it when creating a new shortcut.

  1. Open the Shortcuts app and create a new shortcut
  2. Click the the more menu with the ...
  3. Siri uses your shortcut‘s name, so give it something you‘d say out loud, like “Save my location in Portway”

Now we want to add a few ”Actions”.

Pro tip: 💪🏽 You can copy your Project key using your Mac, and paste the key using your iPhone, using iCloud clipboard

  1. Click the + Add Action button
  2. Search for ”Get Current Location” and add that action
  3. Add another action, ”Get text from input”, using that location
  4. Add another action, “Text“, and paste in your read-only key from your project
  5. Add another action, “URL”, and input the following : https://api.portway.app/api/v1/documents/<YOUR_DOCUMENT_ID>/fields

This was a lot of steps. Let‘s see what this should look like before we go to the last step. Let’s say your DOCUMENT_ID is 123. Your URL action should look like: https://api.portway.app/api/v1/documents/123/fields.

align-right

Publish to Portway

Now we‘re going to add the final step, which pushes the location information to Portway. Refer to the screenshot here, as this can be a little confusing for newcomers.

  1. Add another action to your Shortcut, named "Get contents of URL”
  2. Choose the URL from previous step as the URL for this action
  3. Expand the options by clicking “Show more”
  4. For “Method”, select “POST”
  5. Click on “Headers” and add the following 2 headers:
    1. Content-Type: application/json
    2. Authorization: bearer Text (You can use the magic wand to select the variable)
  6. For “Request Body”, select JSON, and add the following 3 fields
    1. name should be a string
    2. value should be a string, selecting Current Location from the “Variables”
    3. type should be the number 2

Now you’re ready to test this! Click the “Play” button and watch it go! Visit your new document and refresh to see the location information. Try asking Siri to save your location!

What did I just do?

If all went to plan, you just created a simple API request to Portway. APIs allow anyone (usually programmers) to interact with applications. You just used the Portway “fields” API to add a new field to an existing document. You could add, remove, chabnge, or re-order fields in your document all by using the Portway API. You could even create projects and documents that way, though that'd be pretty rough with Siri and Shortcuts.

What else could you do with your content and notes? What other automations interest you? Drop us a line, we‘d love to hear from you!