How to backup your Personal Developer Instance (PDI)

[Earl Duque]

Backing Up Your Personal Developer Instance (PDI)

One of the ongoing issues 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's always possible to have a time period where you're out of office and miss the email about your Developer Instance expiring. We don't like the idea of anyone losing their work, but there's 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: request another, reinstall from backup, and proceed ahead.

There are multiple ways to back up your instance. Below we go over three in depth:

• Studio
• App Engine Studio
• Update Sets

Table of Contents

• How to backup your PDI with Studio
  • Intro
  • Preparation work
    • GitHub
    • Sign up for GitHub
    • Create a personal developer token
    • ServiceNow Credential
  • Save your apps to GitHub via Studio
    • Create a new repository on GitHub
    • Save your app to the new repo
    • Reminders
  • Importing your repository back onto your ServiceNow instance
• How to backup your PDI with App Engine Studio
  • Intro
  • Preparation work
    • GitHub
    • Sign up for GitHub
    • Create a personal developer token
    • ServiceNow Credential
  • Save your apps to GitHub via AES
    • Create a new repository on GitHub
    • Save your app to the new repo
    • Reminders
  • Importing your repository back onto your ServiceNow instance
• How to backup your PDI with update sets
  • Intro
  • Working in update sets
  • Exporting update sets
    • Exporting an individual update set
    • Exporting several update sets together
    • Exporting a scoped application via update set
  • Importing your update set back into ServiceNow

---

How to backup your PDI with Studio

Intro

This section explains how to back up 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'll be using in this walkthrough.

 

Sign up for GitHub

Go to github.com and enter your email address, 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 and keep it 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'll 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 github.com and log in.
2. In 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 back up.
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 the application you want to back up.
3. Once your application is loaded, click 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 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 are not. Need to back up data, too?
  1. Go to the list view of your table
  2. Select the records you want to back up
  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 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 from when you first saved your work to GitHub (don't remember? see below)
4. Click 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 it.
3. Find the branch 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 back up 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'll be using in this walkthrough.

 

Sign up for GitHub

Go to github.com and enter your email address, 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 and keep it 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'll 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 github.com and log in.
2. In 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 back up.
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 the MY APPS tab, then click the application you want to back up.
3. Once your application is loaded, in the top right click the Source Control dropdown 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 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 are not. Need to back up data, too?
  1. Go to the list view of your table
  2. Select the records you want to back up
  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 from when you first saved your work to GitHub (don't remember? see below)
   • Credential: the credential record you created earlier
4. Click 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 it.
3. Find the branch 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 back up 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 fields.
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 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 are not. Need to back up data, too?

1. Go to the list view of your table
2. Select the records you want to back up
3. Select the Create Application File list action
4. Select OK

Exporting update sets

The process is a little different depending on whether you're trying to back up individual update sets, several update sets at the same time, or a scoped application 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 it 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 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 by double-clicking the State value for each row).
   • Set their parent as the update set you created in step 1 (double-click the "(empty)" field 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 it 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 the application you want to back up (click 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 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 it 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 earlier.
4. Click Upload.
5. Open the record for the update set you just imported.
6. Click Preview Update Set.
7. Click Commit Update Set.

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