How to backup your Personal Developer Instance (PDI)

#Git , #GitHub , #Source Control , #Personal Developer Instance , #PDI , #Update Sets , #App Engine Studio , #AES , #Studio , #Version Control

Earl Duque

12 minute read

One of the ongoing issues that we deal with in the Developer Program is the continuity of the free Personal Developer Instances (PDI). No matter how well intentioned you are, it is always possible to have a time period where you are out of the office and miss the email about your Developer Instance expiring. I don’t like the idea of anyone losing their work but there is only so much we can do to prevent it. There aren’t enough resources to give developers free instances that last forever, so we do the best we can.

However, you as the developer have the ability to mitigate this. If you have a backup of everything important to you, then losing your instance is a trivial operation. You request another, reinstall from backup and proceed ahead.

There are multiple ways to backup your instance nowadays. Below we go over three ways in-depth:

Table of contents

How to backup your PDI with Studio

Intro

This section explains how to backup your PDI using Studio (not to be confused with App Engine Studio). This is important information to know because you should always be storing your backups in an external location outside of your PDI.

Preparation work

You will only have to do the following preparation work once.

GitHub

To back up your scoped application using Studio, you will need a version control system called Git. The most popular one is GitHub, which we will be using in this walkthrough.

Sign up for GitHub

Go to https://github.com/ and enter your email address and click Sign up for Github and follow the instructions

Create a personal developer token

GitHub requires personal access tokens to access repositories from other platforms, like ServiceNow. A personal access token is used in place of a password when authenticating.

To create a personal access token:

  1. Use the GitHub instructions to create a personal access token to use with ServiceNow.
  2. Configure the New personal access token.
    • Note: ServiceNow access
    • Expiration: No expiration
    • Select scopes: repo
  3. Copy your token to keep in a secure location. (This is the only time it will ever be revealed, if you don’t save it now, you’ll have to create a new one).

ServiceNow Credential

Now that you have a GitHub account and Personal Access Token. Let’s create a credential record in ServiceNow:

  1. In your filter navigator, navigate to Connections & Credentials > Credentials
  2. On the Credentials table, click New to create a new credential record
  3. You will be asked “What type of Credentials would you like to create?” Choose Basic Auth Credentials
  4. Configure the New Basic Auth Credentials record.
    • Name: GitHub Personal Access Token for [your name]
    • User name: your GitHub account’s user name
    • Password: Your Personal Access Token (not your GitHub account password)
  5. Submit the record

Save your apps to GitHub via Studio

Whenever you want to save your scoped-app work to GitHub, follow these steps for every app:

Create a new repository on GitHub

  1. Go to https://github.com/ and login
  2. On the top right, click the + button and select New repository
  3. Under “Repository name” give it a name that matches the ServiceNow app you want to backup
  4. Click Create repository
  5. Once created note the URL of your repository, it should look like https://github.com/yourusername/your-app-name

Save your app to the new repo

  1. In your filter navigator, navigate to System Applications > Studio
  2. In the “Select Application” window, click on the Application that you want to backup
  3. Once your application is loaded, click on the Source Control header menu item and select Link To Source Control
  4. Configure the Link
    • URL: The repository URL from earlier
    • Credential: The credential record you created earlier
    • Branch: Leave this as is
  5. Click on Link To Source Control

That’s it! You can go back to your repo URL and verify that your files have been saved on GitHub

Reminders

  • Never save passwords, secret tokens, or other sensitive information in a public Git repository!
  • Metadata is not saved, only configuration/application files. For example, a business rule on the Incident table is saved, but incident records on the Incident table are not. Need to backup data, too?
    1. Go to the list view of your table
    2. Select the records you want to backup
    3. Select the Create Application File list action
    4. Select OK

Importing your repository back onto your ServiceNow instance

If you need to bring your work back into ServiceNow from GitHub, follow these steps:

  1. In your filter navigator, navigate to System Applications > Studio
  2. In the “Select Application” window, click on Import From Source Control
  3. Configure the Import
    • URL: The repository URL you want to import
    • Credential: The credential record you created earlier
    • Branch: The branch name when you first saved your work to GitHub. Don’t remember? See below
  4. Click on Import

Forgot your Branch name?

  1. Go to your repository on GitHub
  2. On the Code tab, look for the item that says branches and click on it
  3. Find the branch that you made, it should look like: sn_instances/[your_instance_name]

That’s it! All your work should be back.

How to backup your PDI with App Engine Studio

Intro

This section explains how to backup your PDI using AES (App Engine Studio, not to be confused with Studio). This is important information to know because you should always be storing your backups in an external location outside of your PDI.

Preparation work

You will only have to do the following preparation work once.

GitHub

To back up your scoped application using Studio, you will need a version control system called Git. The most popular one is GitHub, which we will be using in this walkthrough.

Sign up for GitHub

Go to https://github.com/ and enter your email address and click Sign up for Github and follow the instructions

Create a personal developer token

GitHub requires personal access tokens to access repositories from other platforms, like ServiceNow. A personal access token is used in place of a password when authenticating.

To create a personal access token:

  1. Use the GitHub instructions to create a personal access token to use with ServiceNow.
  2. Configure the New personal access token.
    • Note: ServiceNow access
    • Expiration: No expiration
    • Select scopes: repo
  3. Copy your token to keep in a secure location. (This is the only time it will ever be revealed, if you don’t save it now, you’ll have to create a new one).

ServiceNow Credential

Now that you have a GitHub account and Personal Access Token. Let’s create a credential record in ServiceNow:

  1. In your filter navigator, navigate to Connections & Credentials > Credentials
  2. On the Credentials table, click New to create a new credential record
  3. You will be asked “What type of Credentials would you like to create?” Choose Basic Auth Credentials
  4. Configure the New Basic Auth Credentials record.
    • Name: GitHub Personal Access Token for [your name]
    • User name: your GitHub account’s user name
    • Password: Your Personal Access Token (not your GitHub account password)
  5. Submit the record

Save your apps to GitHub via AES

Whenever you want to save your scoped-app work to GitHub, follow these steps for every app:

Create a new repository on GitHub

  1. Go to https://github.com/ and login
  2. On the top right, click the + button and select New repository
  3. Under “Repository name” give it a name that matches the ServiceNow app you want to backup
  4. Click Create repository
  5. Once created note the URL of your repository, it should look like https://github.com/yourusername/your-app-name

Save your app to the new repo

  1. In your filter navigator, navigate to App Engine > App Engine Studio
  2. Click on the MY APPS tab, and then click on the Application that you want to backup
  3. Once your application is loaded, in the top-right click on the Source Control drop down menu and select Link to source control
  4. Configure the Link
    • URL: The repository URL from earlier
    • Branch: Leave this as is
    • Credential: The credential record you created earlier
  5. Click on Link to source control

That’s it! You can go back to your repo URL and verify that your files have been saved on GitHub

Reminders

  • Never save passwords, secret tokens, or other sensitive information in a public Git repository!
  • Metadata is not saved, only configuration/application files. For example, a business rule on the Incident table is saved, but incident records on the Incident table are not. Need to backup data, too?
    1. Go to the list view of your table
    2. Select the records you want to backup
    3. Select the Create Application File list action
    4. Select OK

Importing your repository back onto your ServiceNow instance

If you need to bring your work back into ServiceNow from GitHub, follow these steps:

  1. In your filter navigator, navigate to App Engine > App Engine Studio
  2. Click Import app
  3. Configure the Import
    • URL: The repository URL you want to import
    • Branch: The branch name when you first saved your work to GitHub. Don’t remember? See below
    • Credential: The credential record you created earlier
  4. Click on Import app

Forgot your Branch name?

  1. Go to your repository on GitHub
  2. On the Code tab, look for the item that says branches and click on it
  3. Find the branch that you made, it should look like: sn_instances/[your_instance_name]

That’s it! All your work should be back.

How to backup your PDI with update sets

Intro

This section explains how to backup your PDI using update sets. This is important information to know because you should always be storing your backups in an external location outside of your PDI.

Working in update sets

Any work that you want to be saved and backed up should be in update sets!

  1. Navigate to System Update Sets > Local Update Sets and click New.
  2. Complete the form from the fields in the table.
  3. Click Submit to create the update set. If the picker is enabled and the update set is in the In progress state, click Submit and Make Current to select the new update set as the target for configuration changes.

What does this mean? Now that an update set is “current”, any configuration work you perform will automatically be recorded in this update set. When you think your work is done, set it to “complete” and now it’s ready for exporting.

Note that Metadata is not saved, only configuration/application files. For example, a business rule on the Incident table is saved, but incident records on the Incident table are not. Need to backup data, too? 1. Go to the list view of your table 2. Select the records you want to backup 3. Select the Create Application File list action 4. Select OK

Exporting update sets

The process is a little different depending on if you’re trying to backup individual update sets, several update sets at the same time, or if you’re trying to back up scoped applications via update set.

Exporting an individual update set

An individual update set has no “parent”

  1. Navigate to System Update Sets > Local Update Sets and select the update set you want to export
  2. Set the State to Complete and save the record (if not already done)
  3. In the Update Set form, under Related Links select Export to XML
  4. Save the XML file to your computer and/or upload to a cloud service

Exporting several update sets together

Do you have several update sets and need to export them together quickly?

  1. Create a new update set and note the name that you select for it
  2. Navigate to System Update Sets > Local Update Sets
  3. For all the update sets you want to export:
    • Set their state as Complete, you can do this from the list view but double clicking on the State value for each desired row.
    • Set their parent as the update set you created in step 1, you can double click the “(empty)” here too to edit it in list view
  4. Open the record for the update set you made in step 1
  5. Set the State to Complete and save the record (if not already done)
  6. In the Update Set form, under Related Links select Export Update Set Batch to XML
  7. Save the XML file to your computer and/or upload to a cloud service

Exporting a scoped application via update set

If you need to export an entire application (not just an update set within the application).

  1. Navigate to System Applications > My Company Applications
  2. Click on the application that you want to backup (click on the box itself, not the “Edit in Studio” button)
  3. If the top of your screen says “The [your app name] application cannot be changed because [another app name] is selected in your application picker” Click on Switch to [your app name]
  4. Under Related Links select Publish to Update Set...
  5. In the “Publish to Update Set” window, select Publish
  6. Once the new update set is automatically created and loaded, under Related Links select Export to XML
  7. Save the XML file to your computer and/or upload to a cloud service

Importing your update set back into ServiceNow

If you need to bring your work back into ServiceNow, follow these steps:

  1. Navigate to System Update Sets > Retrieved Update Sets
  2. Under Related Links select Import Update Set from XML
  3. On the Import XML screen, select Choose File and select the XML file you exported from before.
  4. Click Upload
  5. Open the record for the update set you just imported
  6. Click on Preview Update Set
  7. Click on Commit Update Set

That’s it! All your work should be back.

Comments