3 steps to configure Vanilla Forum with Orbit.love

Table Of Contents

• What's orbit
  • Integrations
  • Where's my integration?
• Goal
• 1. Extract VF Members
  • Generate VF Token
  • Script
  • Issues and Improvements
• 2. Import Members to Orbit
• 3. Configure Zapier
  • VF New User Webhook
  • Zapier Webhook Actions
  • Orbit Step
• Tips and Tricks

What's Orbit?

Orbit is a platform that helps with understanding your online community. If you are a developer advocate or a community manager then you can consider this platform as the mission control for your community that consolidates and curates all your members and their activities from different places into one place. It's pretty nifty! At Solace we use Orbit to better understand our community members and where they gravitate to the most.

The Orbit Model Framework helps with segmenting community members into different categories depending on their activities and interactions with the community. This framework is based on associating a weighted score for different kind of activities on different platforms. It's important to understand this model for whats coming next 👀

Integrations

The nice thing about Orbit is the ability to connect multiple different integration from their natively supported integrations. Meaning that any activity that happens on the platform, for example a tweet or a PR on a github repo, can be ported into your Orbit workspace, associate with the user, and given a particular weight for scoring purposes.

Where's my integration at?

If your members are hanging out in a platform that is not natively supported by Orbit as an integration, worry not! Since Orbit was built with developers in mind, they naturally have APIs that facilitates the interaction with the platform via importing users and adding activities.

We use Vanilla Forum (VF) as the community forum solution at Solace. Orbit, however, doesn't have a native integration with VF. What's the solution? lets jump into the API!

Goal

The problem we wanted to solve is the following:

1. Extract all the already existing community members from Vanilla Forum
2. Import the members into Orbit
3. Integrate any new user activity from VF to Orbit: New Users, Comments, New Discussions.

Luckily, VF has an API we can leverage to extract information from the forum. They also have support for Webhooks to facilitate integrations between sites and services whenever any activity happens in the forum.

Let's cut the chase and get to the core of it!

1. Extract existing members. Done once!

Generate your VF Token

To use the VF APIs, you will first need to generate an Access Token. To do so , follow the steps on Authentication With Personal Access Tokens

Write your script

I wrote a simple nodejs application to extract all the members from VF via their APIs into a CSV file. You can use your programming language of choice.

async function getUsers(page) {
  const baseURL = `https://solace.community/api/v2/users?expand=extended&page=${page}`;
  const header_config = {
    method: "GET",
    headers: {
      Authorization: `Bearer <Insert Token Here>`,
    },
  };

  let res = await fetch(baseURL, header_config).catch((err) => {
    throw new Error(`Error fetching content from ${baseURL}. ${err}`);
  });

  if (!res.ok) {
    throw new Error(`Response status from ${baseURL}: ${res.status}`);
  }

  let body = await res.json();

  if (body.length === 0) {
    throw new Error(`No content in page ${page}`);
  }
  // CSV list 
  let content = [];

  body.map((user) => {
    let isEmployee = user.roles[1] ? user.roles[1].name === "Employee" : false;
    content.push(`${user.name}, ${user.email},,,${user.extended.LinkedInprofileoptional},,${user.extended.CompanyName}, ${user.photoUrl}, "VF", ${isEmployee},${user.extended.JobTitleoptional}\n`);
  });

 content.forEach((l) => {
    fs.appendFile("users.csv", l, (err) => {
      if (err) {
        console.error(err);
        return;
      }
    });
  });
}

let content = ['name','email','github','twitter','linkedin','discorse','company','avatar_url','tags','teammate','title','\n'];

fs.appendFile("users.csv", content)

for (let i = 0; i < 39; i++) {
  getUsers(i);
}

Notes

1. The script expects an empty users.csv file to exist
2. The VF API returns the users in several pages. I manually traversed the pages since I knew how many pages I am dealing with for the initial import. You can check out VF's Pagination section for more information
3. The generated CSV file follows the Orbit CSV import guidelines. Use this Template if you want to add other tags associated with the members
4. The script adds a VF tag to the users to make sure we can differentiate our forum users from other users. You can add whatever tags your team decides on adding. This is a comma separated list

Issues and Improvements

1. The Orbit import format does not allow for specifying the joined_at parameter, so all your imported members will have the joined date as the day you import the members to your workspace
2. Pagination could be improved in the script above

Now that you have your CSV file ready, lets import the members to Orbit!

2. Import your CSV file to orbit

1. Navigate to the setting section in your workplace
2. Import your CSV File
3. Wait for the import to finish

We're ready to configure Activities! 👇

3. Connect Webhooks to Orbit Activities

Vanilla Forum has support for Webhooks to integrate with other websites and services. You can use integration services like Zapier or SendGrid to leverage the VF Webhooks. In this tutorial I will be using Zapier and assume you already have an account.

Vanilla Forum new user webhook

1. Create a new zap and search for the Vanilla Forum app
2. Configure the connection parameters
3. Choose the event you want to trigger the zap with. I chose new user added
4. Test the trigger and observe the output

Note

It's important to note that some metadata are not included in the body of the webhook such as the company name and Linkedin profile. Depending on what other parameters you have configured in your VF sign up form, you might want to include other metadata associated with every user.

🚀 Zapier Webhook Actions for the rescue!

Zapier Webhook Actions

We will need to add another step after the Vanilla Forum step. This will leverage VF's REST APIs to query further parameters for the new user.

1. Click on the '+' sign to add another step
2. Search for "Webhooks By Zapier"
3. Under the Action event, choose GET
4. Under the Setup Action, fill in the URL https://<your_domain>/api/v2/users/{userID}?expand=extended
   • Note that the userID is obtained from the previous step. The expand=extended parameter is needed to get extra metadata for the newly added user. Check Expanding User Profile Extender Fields
5. Add an Authorization Header under the Headers section with a value of Bearer <Insert VF Token>
6. Click continue and Test the integration

Orbit Step: Add new user

Now that we have all the metadata associated with creating a new user, we are ready to add the user to Orbit

1. Click on the '+' sign to add a new step
2. Search for orbit
3. Choose "Create a new Member" from the actions events
4. Fill in the information either statically (by typing it in) or dynamically (from the output of the previous step)
5. Dont forget to add a tag for every activity! For Example VF for a new user, VF-Discussion for a new discussion, and VF-Comment for a new comment
6. Click continue and test action
7. Turn on the Zap

And you're done! Now everytime a new user joins your community forum, a webhook is triggered to Zapier, and the Zapier configuration will add that user to Orbit leveraging Orbit's APIs and the details in your step.

You can follow the same steps for new discussions and new comments webhooks. Make sure you add the right tags for every activity!

Tips and Tricks

• Adding all the tags and information associated with every activity is extremely crucial. This comes to play and becomes helpful when you want to filter members or activity based on a particular tag
• You can modify the weight for every activity. This can be fine tuned and decided by you and your team.