DISCUSSION: Should we merge integration website content into flexio.yml file?

[dzwillia]

We only have a dozen or so integrations right now and, as we continue to roll them out, I've had a few thoughts on "pinch points" in the process.

Right now, when we want to add a new integration, we have to do the following:

1. Create a new repo named "functions-<integration-name>" which includes the scripts that contain the logic as well as a flexio.yml file.

2. Make sure we have a logo for the integration -- add the logo file to the flexiodata/flexio-static repo.

3. Add the repository header information to integrations.yml both in the flexiodata/flexio-static repo as well as the flexiodata/website repo.

   - repository: https://github.com/flexiodata/functions-intercom
     connection:
       name: intercom
       title: Intercom
       icon: https://logo.clearbit.com/intercom.com
       connection_type: http
       connection_status: A
       connection_mode: F
       connection_info:
         url: https://static.flex.io/integrations/functions-intercom/flexio.yml
     in_production: true
     in_staging: false

4. Update the update-integrations.bat with the repo name in the flexiodata/flexio-static repo as well as the flexiodata/website repo.

5. Run update-integrations.bat in the flexiodata/flexio-static repo as well as the flexiodata/website repo and push the changes. (NOTE: Pushing changes to the flexiodata/flexio-static repo will trigger a rebuild of the static site via Netlify).

6. Create a .yml file with all of the website content (including/duplicating most of the information from its respective flexio.yml file) in the src/def/integrations folder in the flexiodata/website repo.

7. SSH into test.flex.io, rebuild the website and make sure everything looks good:

   • flexio-ssh test-website1
   • sudo -s
   • cd /srv/www
   • ./update website

8. Repeat step 7, but for www.flex.io:

   • flexio-ssh prod-website1
   • sudo -s
   • cd /srv/www
   • ./update website

So, much of this is relatively trivial stuff, however, one thing that we're running into that is somewhat annoying and causing problems is the multiple sources of truth. There's the function pack repos (in 3 places!), there's the integrations.yml file (in two locations), there are multiple update scripts that have to be edited and then there's the website content file (also a .yml file) for the integration. (I will include an example of these files as part of this issue)

I feel like this is the sort of thing that can be sorted pretty easily by merging the YAML file we use for the website content into the flexio.yml file in each function pack. This would give us a single source of truth. The only downside to doing this is that when someone forks that repo, they would be able to see some of the info we use (keywords, Markdown) that we use to render the integration page on our website. Dunno... I don't think that's a very big deal. Right now, the YAML that builds the form that we use in the app is already included.

Certainly don't want to get sidetracked with an "organization/optimization" project right now, however, I believe this wouldn't take more than a half a day or so to get sorted and I think it might make this far more straightforward as we add more. (I'm also think forward to the couple of weeks I'll be out of pocket once the baby arrives and trying to make sure this is manageable for you all).

Thoughts?

---

flexio.yml (in functions-intercom repo)

title: Intercom Function Pack
description: Functions for accessing your Intercom info
image:
  src: https://logo.clearbit.com/intercom.com
  alt: Intercom logo
functions:
  - path: intercom-enrich-users.py
  - path: intercom-list-events.py
  - path: intercom-list-signups.py
prompts:
  - element: auth
    name: auth
    title: Connect to Intercom
    description: |
      Connect to your Intercom account to connect the functions to your data
    connection:
      connection_type: intercom
    form_items:
      - name: intercom_connection
        value: ''

intercom.yml (in src/def/integrations folder in flexiodata/website repo)

name: intercom
display_name: Intercom
title: Integrate and Import Intercom into Microsoft Excel or Google Sheets
description: Import live, refreshable data from your Intercom account into Microsoft Excel and Google Sheets. Easily work with Intercom data without leaving your spreadsheet.
keywords:
  - intercom
  - spreadsheet
  - excel
  - google sheets
  - integration
  - import
  - export
  - extract
icon: https://logo.clearbit.com/intercom.com
header: Intercom in your spreadsheet
subheader: Import live, refreshable data from your Intercom account in Microsoft Excel and Google Sheets.
content: |

  ## Import Intercom data in your spreadsheet

  This collection of Intercom spreadsheet functions enables you to collect or analyze data from your Intercom account directly from your spreadsheet. For example, pull in on-demand, refreshable extract lists from Intercom. Or, enrich existing data in your spreadsheet with lookups from Intercom.

  [Learn more about Intercom spreadsheet functions and syntax here.](#functions-and-syntax)


  ## Getting Started

  Flex.io makes it easy to create, use and share custom spreadsheet functions that import data from services you know and love. Click on the button below to use the Intercom function collection with Microsoft Excel or Google Sheets. **Please note that you'll need an Intercom account to use this integration.**

  <div class="tc mt4">
    <a href="/app/start?integration=intercom" class="db dib-ns pv3 ph5 tc b ttu blue br2 ba b--blue hover-bg-blue hover-white" target="_blank">
      Get started now
    </a>
  </div>


  ## Need Help?

  Have questions? Need help with installation? Need other Intercom functions for Microsoft Excel or Google Sheets? [Chat with us; we're happy to help!](#js-show-intercom-messenger)

Proposed flexio.yml file with website content merged in

name: intercom
display_name: Intercom
title: Integrate and Import Intercom into Microsoft Excel or Google Sheets
description: Import live, refreshable data from your Intercom account into Microsoft Excel and Google Sheets. Easily work with Intercom data without leaving your spreadsheet.
keywords:
  - intercom
  - spreadsheet
  - excel
  - google sheets
  - integration
  - import
  - export
  - extract
image:
  src: https://logo.clearbit.com/intercom.com
  alt: Intercom logo
functions:
  - path: intercom-enrich-users.py
  - path: intercom-list-events.py
  - path: intercom-list-signups.py
prompts:
  - element: auth
    name: auth
    title: Connect to Intercom
    description: |
      Connect to your Intercom account to connect the functions to your data
    connection:
      connection_type: intercom
    form_items:
      - name: intercom_connection
        value: ''
header: Intercom in your spreadsheet
subheader: Import live, refreshable data from your Intercom account in Microsoft Excel and Google Sheets.
content: |

  ## Import Intercom data in your spreadsheet

  This collection of Intercom spreadsheet functions enables you to collect or analyze data from your Intercom account directly from your spreadsheet. For example, pull in on-demand, refreshable extract lists from Intercom. Or, enrich existing data in your spreadsheet with lookups from Intercom.

  [Learn more about Intercom spreadsheet functions and syntax here.](#functions-and-syntax)


  ## Getting Started

  Flex.io makes it easy to create, use and share custom spreadsheet functions that import data from services you know and love. Click on the button below to use the Intercom function collection with Microsoft Excel or Google Sheets. **Please note that you'll need an Intercom account to use this integration.**

  <div class="tc mt4">
    <a href="/app/start?integration=intercom" class="db dib-ns pv3 ph5 tc b ttu blue br2 ba b--blue hover-bg-blue hover-white" target="_blank">
      Get started now
    </a>
  </div>


  ## Need Help?

  Have questions? Need help with installation? Need other Intercom functions for Microsoft Excel or Google Sheets? [Chat with us; we're happy to help!](#js-show-intercom-messenger)

[wanderslth]

Sorry -- just saw this. Hmm.

There are a few potential issues I can see here:

1. We don't yet know, is whether the functions- is a flex internal thing or will be forked/used by devs. If the latter, this is a pretty heavy dump of crap into the otherwise clean repo.
2. Right now it is super easy for me to tweak this via my normal website updates -- placing these in the functions-repo makes this far less accessible, especially when I go down the line and edit all 10 in one shot like I do now for meta tags, titles, etc as we iterate (this will slow down, but right now I'm doing edits on these once a week.. in fact will be doing another round tomorrow).
3. The flexio.yml is primarily for use with the New > integrations to tell them how to handle the token/oauth, no? The servicename.yml is website display only, no?

To me, the creation of a new intercom.yml takes all of 5 minutes (copy/paste, find/replace name) and doesn't seem to be the core showstopper in all the above efforts that you're making. Maybe I'm missing something, but seems like if you automated everything else EXCEPT the final website servicename.yml file, the latter would be a trivial thing for us to add manually?