FreePBX 15 is Released!

Hello Everyone!

We’d like to announce that FreePBX 15 is now fully released! It has been a long road in getting things shored up with some of the new included functionality but we’re very excited that we’ve finally come to this moment. I’d like to take a moment to thank all of you who have helped to test, submit bugs, submit patches, answer questions on the forums, and otherwise participated in getting this release out. It takes the diligent efforts of many to ensure that everything comes together.

As a final note, updated ISOs should be available on the download site with updated versions of SangomaOS and FreePBX 15. Thanks so much again, and happy upgrade/release day to you all!

– The FreePBX Dev Team

FreePBX Team Update

Hey,

The last few blog posts we’ve done have been technical, so this week I’d like to take a step back from that and introduce you to some recent additions to the FreePBX team. As a company, we have been redoubling our investment into the FreePBX project, and it’s good from a community perspective to see some of the fruits of those efforts.

The first person is Walter Moon (picture above). Walter began his career in telecommunications back in 2005 at Switchvox, during its earlier days. “During my time in multiple roles with Switchvox, I built a good understanding of how companies use a PBX, and what they expect from them. That perspective really helps when I approach things as a developer.” After joining the FreePBX team in June of this year, he’s looking forward to what’s to come, saying “I’m happy to be on board as a developer for the FreePBX team. The benefits of being an open source project are notable, and it’s exciting when there’s a strong community contributing in numerous ways. It keeps things interesting. I always liked FreePBX as a product. It offers so much for so little cost. It’s something I’d use myself, and I like that.“ When he’s not working, Walter likes to spend his time tinkering with cars, and playing video games.

Another recent addition is Matt Brooks (also pictured above). Like Walter, Matt also began his career at Digium in 2005. For the most part, Matt has worked many years behind the scenes at Digium and Sangoma building the website infrastructure and business systems. “I’m excited to make the transition from a supporting development role to an active product development role in FreePBX. I have been playing around with Linux and Open Source software since I was a teenager and finally getting the opportunity to work on a Great Open Source Project, such as FreePBX, has always been a dream of mine. I have many ideas for the project and I can’t wait to see how I can apply them to help push the project forward.” Matt’s hobbies outside of work include building and supporting local tech communities in Huntsville, AL by organizing technical workshops and innovation competitions through local non-profit Urban Engine. Here, Matt has been key in organizing many events such as the NASA International Space Apps Challenge, the Hudson Alpha Tech Challenge, HackHSV High School Hackathon, and 4 Hours to Product.

I think we’re excited as a team to see them grow into their roles as FreePBX developers and start interacting with different members of the community. Hope you all enjoyed getting to know Matt and Walter a bit better, and best wishes to you all!

– Matthew Fredrickson

GraphQL support in FreePBX 15

As you’re probably already aware, we’re very close to the release of version 15 of FreePBX.  One of my favorite new features in FreePBX is the GraphQL support that was added earlier this year.  The support that was added for GraphQL makes it easier for external programs or systems to interact with a FreePBX system.  For those of you not familiar with GraphQL, I hope this blog post makes a good introduction, and helps you to catch my enthusiasm for supporting GraphQL in FreePBX.

What is GraphQL?

GraphQL is a more modern way of programmatically querying applications. GraphQL allows the API user to be more specific about the query they would like to issue to the API. This allows the interaction between the client and server to be more streamlined, make fewer API calls, and be more performant.

GraphQL is a “data query language”, that was developed by Facebook.  It is a specification for how to query an API over HTTP or HTTPS. You can think of it as being somewhat REST-like, but more declarative.  With typical REST APIs, you ask the server to send you a representation of some sort of object. For example, you might do an HTTP GET to http://my.example.com/rest/v1/book/42 and the server would return some sort of stateful representation of object “book” with an identifier of “42”.  If the “book” object has a large number of fields, the server is going to return every single one.

GraphQL is also used to query a server via HTTP or HTTPS and get a response — just like REST.  Unlike REST however, GraphQL lets you specify the exact fields that you want returned. How? A client tells the GraphQL server exactly what it wants the response to look like, by sending the server the layout it wants for the responses.  For example, let’s assume we have a GraphQL server that serves up information about books. The following GraphQL query shows how you would query the server to get the book with ID 42, with only its ID and title fields returned:

query {
  book(id: 42) {
    id
    title
  }
}

Why GraphQL instead of REST?

GraphQL is better at dealing with hierarchical data.  To extend our “books” example a bit more, let’s say that each book has a link to an “author” object as well.  Using REST, we’d have to GET a book object, parse the response to get the author ID, then GET the author object with that ID.  It makes for a lot of back-and-forth requests for linked data. GraphQL, on the other hand, follows relationships between objects.  For example, the following example query would automatically follow the link between the book and the author, and return the “firstName” and “lastName” of the author(s) associated with the books.

query {
  allBooks {
    book {
      id
      title
      author {
        firstName
        lastName
      }
    }
  }
}

GraphQL is also strongly typed.  This means each field is either a built-in type (such as a string or an integer), or a specified type (such as a book or an author).  With GraphQL, you never have to worry about what type of values you’re going to get back from the server.

GraphQL comes with a set of default scalar types out of the box:

  • Int: A signed 32‐bit integer.
  • Float: A signed double-precision floating-point value.
  • String: A UTF‐8 character sequence.
  • Boolean: true or false.
  • ID: Represents a unique identifier for an object

Of course, a GraphQL server can (and often does!) define its own custom types.

GraphQL is also introspective.  This means that there is built-in support for asking the server which methods are available, and which types of data can be returned.  This makes a server self-describing in a way that makes it much easier for developers to explore the API and understand the results. Some GraphQL clients use this introspection to make developing with GraphQL much easier, as will be explained below.

GraphQL basic concepts

GraphQL has three basic types of operations that you can perform: queries, mutations, and subscriptions.  A query is a request for information from the server. A query typically begins with the word “query”, and then the method you are querying, along with the details from that query that you want returned.  For simplicity’s sake, if you leave off the word “query”, GraphQL will assume you’re doing a query. This means that the following two queries are functionally identical:

query {
  book(id: 42) {
    id
    title
  }
}

{
  book(id: 42) {
    id
    title
  }
}

Mutations are used to either create a new object, or to change values on an existing object.  You can think of them as being roughly analogous to using POST, PUT, and PATCH on REST APIs. In the case of GraphQL, however, you’re always using an HTTP POST for your queries, mutations, and subscriptions. For example, the following mutation could be used to create a new book in our example API, and then return its ID:

mutation {
  createBook(input: {
    author: "John Q. Public",
    title: "Hoping for Better Weather",
  }) {
    id
  }
}

The last basic operation is a subscription.  You use subscriptions to be notified when a new object is created, or an existing object is modified.  Assuming the API has a subscription type of “newBook”, the following example would wait until a new book is created, then return it’s title and ID.

subscription {
  newBook {
    id
    title
  }
}

How do I get started with GraphQL in FreePBX 15?

Now that we have covered the basics of GraphQL, let’s dive into using the GraphQL support in FreePBX 15. To begin with, you’ll want to make sure that all of your FreePBX modules are up to date, and that you have the “API” module installed.

IMPORTANT NOTE: Please note that GraphQL support in FreePBX 15 is a technology preview, and that GraphQL support has not been added to every single FreePBX module. Over time, we hope to expand the GraphQL support in FreePBX to cover more modules and more functionality.

Once that is done, you’ll want to create a new API “Application” in FreePBX. Simply go to the FreePBX administrators panel, and choose “API” from the “Connectivity” menu. Then click on the “Add Application” button and choose “Machine-to-Machine app” as shown below:

Adding a Machine-to-Machine App

On the next page, give your application a name (such as “GraphQL demo”) and a description.  For now, leave the “Scopes” field empty. Scopes are a way of limiting the permissions of an application, but by leaving the field blank, we’re giving this application full permissions.  Click on the “Add Application” button.

On the next page, you’ll be presented with all the necessary information to connect to FreePBX via GraphQL.  Your information will obviously be slightly different than mine, but it should look something like the following:

It is vitally important that you copy the “Client Secret” because as soon as you hit the “Close” button you cannot retrieve that value.

Now that we’ve created application credentials, we can use them to play with GraphQL.  There are two methods for doing this. The first is the built-in GraphQL Explorer panel.  The second is using an external application. I’ll briefly explain how to use both.

Using the GraphQL explorer

Within the API module in FreePBX, simply click on the “GraphQL” explorer tab.  Then, simply type “gql” in the scopes text box, and click the “Reload Explorer” button.  This will load the GraphQL explorer with the “gql” scope, which means that you’ll be able to see everything with GraphQL.

GraphQL Explorer Scope

You’ll then see the GraphQL Explorer interface, which allows you to test GraphQL queries and mutations directly from your web browser.  For example, type the following query to get a list of all the FreePBX modules on your system and their current version:

{
  allModules {
    modules {
      name
      version
    }
  }
}

GraphiQL Explorer

Note how the “data” object returned matches the layout of our query? That’s one of the beauties of GraphQL — the results match the format and layout of the query.

Use an external program for testing

Another way to interact with GraphQL (without writing your own GraphQL client in the programming language of your choice) is to use an external program.  There are two popular REST development clients which have added GraphQL support, namely Postman and Insomnia. Since Insomnia was the first to support GraphQL and seems to have more robust GraphQL support, I’ll show you how to configure Insomnia to connect to the GraphQL endpoint in FreePBX.

First, download and install the Insomnia program from https://www.insomnia.rest.  Insomnia has clients for Linux and Mac and Windows.  Once the program has installed, run the Insomnia client.

Click on the “New Request” button, give the request a name, select “POST” as the request type, and “GraphQL Query” as the body type.  Then click the “Create” button.

Create Request

First, let’s tell Insomnia where to send GraphQL requests.  In the URL bar at the top (to the right of where it says “POST”, enter the GraphQL URL from the client credentials we created above.  From my example credentials, the URL would be http://192.168.55.153/admin/api/api/gql. Yours will obviously be slightly different.

GraphQL URL

Next, click on the “Auth” tab at the top of the middle pane.  Click the small arrow next to “Auth” to open the drop-down, and select “OAuth 2”.  Select “Client Credentials” as the “Grant Type”. Enter the Token URL from the client credentials, as well as the Client ID and Client Secret.  Make sure the “Enabled” box is checked. Now, click the “Refresh Token” button at the bottom of the screen. If the “Access Token” is filled in with a long list of letters and numbers, your authentication is working correctly.  If you get a 401 error instead, double-check your Client ID and Client Secret and try again.

GraphQL Authentication

Finally, we can write our query in the “Body” tab.  For our first query, let’s list the FreePBX modules and their versions.  Click the small arrow next to the “Body” tab, and select “GraphQL Query”.  Then type (or copy/paste) the following query in to the “GraphQL” tab:

query {
  allModules {
    modules {
      name
      version
    }
  }
}

Now we can press the “Send” button, and see our results:

GraphQL results

There you go!  You’re on your way to playing with GraphQL and FreePBX 15!  Feel free to look at the documentation, either in the GraphQL Documentation tab in the API module of the FreePBX GUI, or by clicking on the “schema” button in Insomnia.

Technology Preview

Just as a final reminder, please remember that GraphQL support in FreePBX 15 is a technology preview.  Not all of the desired functionality has been baked into the FreePBX 15 release. Future module updates will likely add additional functionality to the GraphQL API.  We hope that this blog post inspires you to start looking at the GraphQL API.  Please give us feedback on what features you would like to see added to FreePBX in the future!

FreePBX 15 – Backup and Restore Rewrite

First, some history: we started development of the new backup and restore system in mid 2017. Some of the goals of that effort were to redesign the feature to allow for more simplicity, flexibility, and maintainability.

Some of the major reasons it was decided to rewrite include:
– There was no choice for backup on a per module basis.
– There was no option to restore the backup from an older version to a newer version.
– No choice of restoring only a particular module.

The redesign ended up being a new concept/structure of taking backup from the way it used to be. Each module handles its own backup and restore. This makes the QA process more complicated due to having to test each and every module and many combinations of modules.

New Backup & Restore functionality:

The new backup and restore functionality in Freepbx 15 is very simple and easy. Each module handles its own backup and restore implementation. It allows you to do backups per module – and 15 backup does only the data backup so it is very lightweight. Prior to 15, backup could potentially include not just configuration files and database information, but also could include FreePBX PHP files and other similar unnecessary additional program related data (depending on how a user constructed their backup templates). In FreePBX 15, we have also removed the backup templates concept from backup and restore to make the backup data selection process more simple and clear for users. We decided that the previous template system was overly complicated for what it was intended to do. If someone is not familiar with the details of which underlying applications and modules needed to be backed up, it was challenging to figure out how to properly construct a template for some particular part of the system. The new system simplifies the module selection interface and it allows you to restore any particular module from a full backup. So if users would like to backup or restore only one particular module, the new interface allows users to easily do so.

FreePBX 15 backup also allows you to restore from legacy backups. This means that people can take a backup from an older version of FreePBX (specifically versions 13 and 14) and restore to a FreePBX 15 system. This makes it easy for the users of FreePBX to migrate from older versions to a new or more current major version of FreePBX.

Backup storage options are now handled in the Filestore module which offers more options on where to store your backups. These options include local storage, remote FTP, SSH/SCP, Amazon’s S3, Email, and Dropbox.

As previously mentioned, due to the scope and complexity of these efforts, it required a much longer QA cycle to make sure it was ready to go (or ready enough). That being said, we hope it to be a lot more “baked” at release time than it would have been otherwise.

We hope you all are able to enjoy and try this new functionality out. As always, for any issues that are found, feel free to open a bug at issues.freepbx.org.

Thanks,
Philip Joseph

FreePBX 15 Release Candidate Announcement

Hey All,

Before I get down to business, I’d like to introduce myself to you, as I don’t think I’ve had an opportunity to do so. My name is Matthew Fredrickson, and I’m the new FreePBX project lead at Sangoma. I began working at Sangoma as a part of the Digium acquisition and have had the role of Asterisk project lead for the last few years. After Andrew decided to leave Sangoma, the leadership at Sangoma asked me if I would be willing to step in and work with the many great developers and community members of FreePBX in addition to those of the Asterisk project. Taking on that mantle from Andrew has been no small undertaking, but has been an enjoyable opportunity for me to grow as well.

My background in telecommunications started in 2001 when Mark Spencer asked me to work for him doing open source software development with Asterisk. Over the years, I’ve had the opportunity to do extensive work on DAHDI, Asterisk, and many of Digium’s traditional telephony products. The acquisition by Sangoma allowed both Digium’s and Sangoma’s world class teams to come together and try to improve our part of the telecom industry in a more synergistic way.

All that being said, my goal today is not to go extensively into my own past, but to write about the present. Today, we’d like to announce that the FreePBX 15 branch is graduating from beta into a release candidate phase. This is the final step that will take place prior to an official FreePBX 15 release. The goal is to have an approximately 4 week period in the release candidate phase and have all major issues and regressions resolved by the end of the month, at around Astricon time (Oct 28-Oct 30 or so). So for those of you who like to test new releases, please do your best to test things in the FreePBX 15 branch so that we can get as many pesky bugs knocked out as possible prior to a final release.

In conclusion, I want to thank all of you that contribute regularly to the FreePBX project – whether it be in the forums answering questions, doing code level contributions, or all the many other ways there are to directly and indirectly contribute. I have learned in my work with the Asterisk project that it takes a lot of time and effort from not just one, but many individuals to help make all the parts of an open source project to run smoothly.

Also, be on the lookout over the next few weeks for a few blog posts editorializing some of the new features in FreePBX 15.

Happy testing to you all, and best wishes!

Matthew Fredrickson