This blog post is Human-Centered Content: Written by humans for humans.

“Don’t Panic”

The words printed on the cover of Douglas Adams’s Hitchhikers Guide to the Galaxy ring true in the case of disasters such as this. Luckily, thanks to Sigma’s API, restoring a lost connection does not need to be such a headache.

I am going to take you through the steps to restore a lost connection in case a “friend” has accidentally deleted one. All the steps detailed below require admin access in Sigma but so does deleting a connection.

Getting Your Credentials

The first thing you’ll need to start helping your “friend” fix their mistake is your client ID and client secret for Sigma API, as well as the correct request endpoint depending on your host.

These are all found under the Developer access UI in the administrative view.

• Click on the profile action in the top right
• Select administration (you will need admin privileges for this of course):

• You’ll find Developer access on the bottom left with a key icon:

I recommend getting out your handy dandy notepad, as you’ll want a few things readily available for copying and pasting.

The first thing you need to grab is the API base URL, this is the endpoint you’ll be requesting from the API and it is automatically generated here based on your cloud provider:

Next, you’ll need a Client ID and Client Secret.

• Click the “Create New” button in the top right corner:

• Select REST API, complete name and description as you please, and assign yourself as the owner.
• Click Create:

Once you create the client credentials, a box will pop up with the newly generated Client ID and Client Secret. Copy them both and record them in a secure location (your handy dandy notebook, perhaps).

Okay, now that we have our credentials, we can start looking for our lost connection.

Finding the Lost Connection

Sigma’s API has information on all connections that your organization has made (archived or otherwise). The key piece of information we are looking for from the lost connection is the connectionId.

• First go to Sigma’s List Connections page.
• Make sure the URL matches the one we copied earlier:

• Enter your client credentials and authorize the token. This will generate a Bearer. I recommend copying this and saving it as well:

• Under QUERY PARAMS, find includeArchived and set it to true. This will allow your lost connection to come through in the request, SO DON’T SKIP IT!

• Click the “Try It!” button underneath the automatically generated code:

You should be greeted with a list of all the connections associated with your organization, active or otherwise. If not, go back to the top of the page and make sure all of your information is correct:

You are looking for the “connectionId” of the deleted connection. There is a chance that the “name” of the connection is somewhat different from what you may remember, so look for clues in the response such as “lastActiveAt” and “isArchived.”

You should also record the name just to be safe, but you probably already know the name because it has been popping up on all sorts of error messages recently.

Now that we have the connectionId of the lost connection we can (hopefully) update that connection to restore it.

Updating the Connection Via API

No more messing around; we are almost there!

• Go to Sigma’s Update Connections page.
• You may have to enter your credentials again or re-authorize your token.
• Start filling out Params. The most important ones are:
  • connectionID (we got this in the last step)
  • details. Here, you will need to fill out the details of our connection. This should be pretty similar to the information you use when creating a connection in Sigma
  • name (ideally this should match the original name of the connection)
  • Set “restore” to “true.” This is SUPER IMPORTANT because it is what will restore the connection:

Including more details is generally better here.

You may also find issues where you are getting “Unable to connect to host” messages. This can be caused by formatting issues relating to authentication strings. This happened to my “friend” when copying and pasting the connection key — the line escapes “\n” were not being imported into the website correctly. If this happens to you (or your friend), I recommend copying the request code from the website in the language of your choice and pasting it into your coding environment, then you can control the formatting of your authentication strings much easier.

You will know you have succeeded when you get a response that looks very similar to the one which was returned when we requested the connectionId in the last step: A JSON response of updated connection information.

Clean Up

Now you should see the lost connection returned home in your Sigma environment. You may still see some errors in your workbooks but remember: Don’t Panic. It may take some time and refreshing for everything to return to order. You may also find some straggler workbooks that still have errors in the published version but are fine in edit mode. Simply republish the workbook and the errors should resolve.

Prevention

The best way to deal with these kinds of mistakes is to prevent them in the first place. Follow industry best practices and use test environments before publishing to production. When making changes to a connection, create a new connection instead to ensure the original (as well as its dependencies) are not compromised. After ensuring this new connection is working as expected, you can edit the original/production connection to match the new functionality. Limit the number of users in your organization with admin privileges to only those who need them.

Additionally, you can enable Sigma’s Audit Logs for your organization to easily keep track of changes made to the environment. For example, you can find the connectionID of an archived connection in the audit logs. Look for something like this:

Chin up

These things happen. As long as you don’t panic, you will be fine! Did this blog help you get out of a sticky situation or find yourself in another one? InterWorks is here to help!