Git Configuration

The Git Integration supports Charts, Dashboards, Views and Snippets. Below is the structure of the Git repository and the structure of each object's configuration files. Site Administrators can refer to the Connecting a Git Repository page for instructions on connecting to Periscope.

Table of Contents:

<UL>
<LI><a href="#Directory">Directory Names</a></LI>
<LI><a href="#RepoStructure">Repository Structure</a></LI>
<LI><a href="#ConfigFiles">Configuration Files</a></LI>
<UL>
<LI><a href="#View">View Settings YAML</a></LI>
<LI><a href="#Snippet">Snippet Settings YAML</a></LI>
<LI><a href="#Charts">Chart Settings YAML</a></LI>
<LI><a href="#Dashboards">Dashboard Settings YAML</a></LI>
<LI><a href="#Filters">Configuring Filters YAML</a></LI>
<LI><a href="#Daterange">Specifying YAML for Default Date Range Filter</a></LI>
</UL>
<LI><a href="#Notes">Notes</a></LI>
</UL>

<a name="Directory"></a>

Note: Git Integration is available on select plans. Site administrators can contact their Account Manager for additional information.

<HR>
<a name="RepoStructure"></a>

Directory Names

Dashboard and chart folder names will have a unique ID appended at the end. See example below.

<blockquote><br>my_chart.d4b92e8db89d46c98abccf4460c33b92</blockquote>

These tokens are automatically generated by Periscope once an object is created regardless of whether it was created in-app or from git.

Users should not modify or delete the tokens from existing objects. The tokens are used to map objects between the git repo and the Periscope application. Therefore, modifying or deleting will lead to undesired consequences.

Repository Structure

The repository will be structured as follows:

<blockquote><br>
dashboards/ <br>
├── dashboard_name_1.[token]/   //Token to ensure name uniqueness<br>
|   ├── dashboard_name_1.yaml //The settings for this dashboard<br>
|   ├── chart_name_1.[token]/ <br>
|   |   ├── chart_name_1.py   //Or *.r if chart contains R code<br>
|   |   ├── chart_name_1.sql //The SQL query for this chart<br>
|   |   ├── chart_name_1.yaml //The settings for this chart <br>
|   ├── chart_name_2.[token]/ <br>
|   |   ├── chart_name_2.sql<br>
|   |   ├── …<br>
snippets/ <br>
├── snippet_name_1/ <br>
|   ├── snippet_name_1.sql    //The SQL query for this Snippet<br>
|   ├── snippet_name_1.yaml  //The settings for this Snippet<br>
├── snippet_name_2/<br>
|   ├── ...<br>
views/ <br>
├── view_name_1/<br>
|   ├── view_name_1.py   //Or *.r if view contains R code<br>
|   ├── view_name_1.sql //The SQL query for this View<br>
|   ├── view_name_1.yaml //The settings for this View<br>
├── view_name_2/<br>
|   ├── view_name_2.sql<br>
|   ├── ...<br>
</blockquote><br>

<a href="#top">Back to top</a>

<a name="ConfigFiles"></a>

Configuration Files

Configuration files in the Git repository reflect all the settings which can be defined for a given object. It is not necessary to define values for all settings since Periscope will interpret missing settings in the YAML file as being set to their default value. However, there are certain fields that are required to be defined which are denoted below.

Note: The YAML keys for Views and Snippets are capitalized with spaces. The YAML keys for Charts and Dashboards are lower cased with underscores instead of spaces (eg. Database Name vs. database_name).

<a name="View"></a>

View Settings YAML

<br><blockquote><br>
Database Name: warehouse    #Required<br>
Code Language: python3.6   #Required if Python or R code exists. Valid entries: r3.2, python2.7, python3.6<br>
Settings:<br>
  Materialize View: true     #Required<br>
  Publish As Dataset: true<br>
  Exclude From Auto Archive: false<br>
  Metadata:<br>
    Tags:<br>
    - tag1<br>
    - tag2<br>
    - tag3<br>
    Description: This is my view description<br>
    Owner: owner@periscopedata.com     #Required<br>
</blockquote><br>

<a href="#top">Back to top</a>
<a name="Snippet"></a>

Snippet Settings YAML

<br><blockquote><br>
Parameters:<br>
  - Numerator<br>
  - Denominator<br>
Settings:<br>
  Metadata:<br>
    Tags:<br>
    - tag1<br>
    - tag2<br>
    - tag3<br>
    Description: This is my snippet description<br>
    Owner: owner@periscopedata.com    #Required<br>
</blockquote><br>

<a href="#top">Back to top</a>
<a name="Charts"></a>

Chart Settings YAML

<br><blockquote><br>
chart_type: table   #Required<br>
database_name: demo   #Required<br>
display_name: Recent Signups   #Required<br>
code_language: python3.6   #Required if Python or R code exists. Valid entries: r3.2, python2.7, python3.6<br>
limit_preview:<br>
  rows: 100   #Setting “rows: null” unchecks the Limit Preview checkbox<br>
encrypted_definition:   YzQ1YzJhZmEyMWIxNGNhM/IXtmPONmuMMHQvzo4yotFEwDsqhbCRZvjJMfmhGNka...   #The encrypted definition for this chart (series settings & format chart settings). Currently only editable from Periscope.<br>
color_theme: My Theme<br>
advanced:<br>
  description: This is my chart description<br>
  enable_csv_download_from_chart: true<br>
  expose_public_csv_url: false<br>
position:   #Required<br>
  left: 0<br>
  top: 17<br>
size:   #Required<br>
  height: 14<br>
  width: 20<br>
</blockquote><br>

<a href="#top">Back to top</a>
<a name="Dashboards"></a>

Dashboard Settings YAML

<br><blockquote><br>
display_name: My Dashboard Name  #Required<br>
disable_filters: false <br>
configured_filters:   #See note below for configuring filters<br>
   hidden:<br>
   - My_Hidden_Filter_1: {} #If no default specified, `{}` is written but `null` and blank are valid inputs too<br>
    - My_Hidden_Filter_2:<br>
       default:<br>
        - label: label1<br>
       value: value1<br>
  visible:<br>
  - My_Filter_1: {} #If no default specified, `{}` is written but `null` and blank are valid inputs too
 <br>
   - My_Filter_2:<br>
       default:<br>
       - label: label1<br>
         value: value1<br>
   - My_Child_Filter:<br>
       default:<br>
       - group: group1<br>
         label: label1<br>
         value: value1<br>
   - Date Range:<br>
       default:<br>
       - 180 days<br>
   - Aggregation:<br>
       default:<br>
       - Daily<br>
dashboard_preferences:<br>
   settings:<br>
       tags:<br>
       - tag1<br>
       - tag2<br>
       dashboard_color_theme: My Theme<br>
       description: This is my dashboard description<br>
       owner: owner@periscopedata.com   #Required<br>
       exclude_from_auto_archive: false <br>
</blockquote><br>

<a href="#top">Back to top</a>
<a name="Filters"></a>

Configuring Filters in Dashboard YAML

  • The “configured_filters” section contains the set of filters that are configured specifically for this dashboard. Filters that are visible or hidden on all dashboards by default which have not been configured specifically for this dashboard don’t need to be listed in the YAML as they are automatically inherited from the globally available set. E.g. If I create a new filter, “Users”, with the “Available on all dashboards by default” setting = true, that new filter will not show up in the “configured_filters” section in the YAML files for existing dashboards. If a user subsequently makes a selection within the “Users” filter and sets that selection as the default for a specific dashboard, then “Users” will appear in the “configured_filters” section in the YAML for that specific dashboard (but no other dashboard).
  • When setting filter defaults in dashboard YAML, “label” and “value” are both always mandatory (except for our two system seeded filters: “Date Range” and “Aggregation”).
  • The “group” key of a filter default is only needed for entries of a child filter. “group” specifies the “value” of the parent filter that the child filter's entry is dependent on. i.e. It is a concrete "parent matching value" for a child filter selection entry as described here.

<a href="#top">Back to top</a>
<a name="Daterange"></a>

Specifying YAML for Default Date Range Filter

When all dates are specified:

<br><blockquote><br>
- Date Range:<br>
    default:<br>
    - All Dates<br>
</blockquote><br>

When a plural count of days is specified:

<br><blockquote><br>
- Date Range:<br>
    default:<br>
    - 3 Days<br>
</blockquote><br>

When one day is specified:

<br><blockquote><br>
- Date Range:<br>
    default:<br>
    - 1 Day<br>
</blockquote><br>

When start and end are both unspecified (Functions like the All Dates option):

<br><blockquote><br>
- Date Range:<br>
    default:<br>
    - start: ""<br>
    - end: ""<br>
</blockquote><br>

When only the start date is specified for a custom range:

<br><blockquote><br>
- Date Range:<br>
    default:<br>
    - start: 2018-01-11<br>
    - end: ""<br>
</blockquote><br>

When only the end date is specified for a custom range:

<br><blockquote><br>
- Date Range:<br>
    default:<br>
    - start: ""<br>
    - end: 2018-02-22<br>
</blockquote><br>

When both the start date and the end date are specified for a custom range:

<br><blockquote><br>
- Date Range:<br>
    default:<br>
    - start: 2018-01-11<br>
    - end: 2018-02-22<br>
</blockquote><br>

When no date range is selected (Functions like the All Dates option):

<br><blockquote><br>
- Date Range: {}<br>
</blockquote><br>

<a href="#top">Back to top</a>

<a name="Notes"></a>

Notes

<UL>
<LI>Periscope places <code>.gitkeep</code> files in the top-level directories of the repository to ensure that the directories exist even if they're empty, since empty directories do not show by default.</LI>
<LI>In order to rename Dashboards and Charts from Git, change the "display_name" attribute in the corresponding YAML file for the object in question. Example: if changing the name of a Chart from “<code>My Chart</code>” to “<code>My New Chart</code>”, set “<code>display_name: My New Chart</code>” in the YAML file. Once that configuration is synced, Periscope will automatically rename the “<code>my_chart.[token]</code>” folder and files to “<code>my_new_chart.[token]</code>”. </LI>
<LI>In order to rename Views and Snippets from Git, change the name of the folder in Git which corresponds to that object. Example: if changing the name of a Snippet named “<code>my_snippet</code>” to “<code>my_new_snippet</code>”, change the name of the “<code>my_snippet</code>” folder in Git to “<code>my_new_snippet</code>”. </LI>
<LI>Snippets with invalid characters in their name, will not successfully sync to your Git repository. For a list of invalid characters, please reference our Snippets documentation <a href="https://doc.periscopedata.com/article/snippets">here</a></LI>
<UL>
<LI style="list-style: none;">Any Snippets that did not get synced to the Git repository can be found on the Version Control Settings page in Periscope:</LI>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://assets.website-files.com/58fe8f93dc9e750ca84ebb16/5babfddc3b59cff9f50eb6bb_gitunsuccessfulsyncss.png"></div></figure></LI>
</UL>
</UL>

<a href="#top">Back to top</a>

Our support team is ready to help