tulip_tables.html

<script src="node-red-tulip-edge/js/tulip_tables_common.js"></script>

<script type="text/javascript">
  (() => {
    const QUERY_TYPES = this.tulip_tables_common.TABLE_QUERY_TYPES;
    RED.nodes.registerType('tulip-tables', {
      category: 'Tulip',
      inputs: 1,
      outputs: 1,
      color: '#65CCB8',
      icon: 'tulip.svg',
      defaults: {
        name: { value: 'tulip-tables' },
        apiAuth: {
          value: '',
          type: 'tulip-api-auth',
          required: true,
        },
        keepAlive: { value: true },
        keepAliveMsecs: { value: 10000 },
        retainMsgProps: { value: true },

        // Which API call to use
        queryType: { value: 0 },

        // String parameters
        tableId: { value: '' },
        queryId: { value: '' },
        aggregationId: { value: '' },
        recordId: { value: '' },
        fieldId: { value: '' },
        linkId: { value: '' },
        sortBy: { value: '_sequenceNumber' },
        sortByFieldId: { value: '' },
        sortDir: { value: 'asc' },
        function: { value: 'sum' },
        filterAggregator: { value: 'all' },

        // Ints
        limit: { value: 10 },
        offset: { value: 0 },

        // Bool parameters
        includeDeleted: { value: false },
        includeTotalCount: { value: false },
        allowRecordsInUse: { value: false },

        // Arrays
        field: { value: [] },
        filters: { value: [] },
        sortOptions: { value: [] },

        body: { value: '{}' }, // JSON body
      },
      paletteLabel: 'tables',
      label: function () {
        // TODO: better naming based on what the api call actually is
        return this.name || 'tulip-tables';
      },
      oneditprepare: function () {
        const node = this;

        // Add retainMsgProps as a property to transition legacy nodes. Set to false since
        // previously msg props were not retained.
        if (!('retainMsgProps' in node)) {
          node.retainMsgProps = false;
        }

        // Whether or not to show keep-alive msecs option
        const updateKeepAlive = () => {
          const keepAlive = $('#node-input-keepAlive').is(':checked');
          if (keepAlive) {
            $('#div-node-input-keepAliveMsecs').show();
          } else {
            $('#div-node-input-keepAliveMsecs').hide();
          }
        };
        updateKeepAlive();
        $('#node-input-keepAlive').change(() => {
          updateKeepAlive();
        });

        // Create dropdown menu of table query types
        const nQueryTypes = QUERY_TYPES.length;
        const querySelect = document.getElementById('node-input-queryType');
        for (let i = 0; i < nQueryTypes; i++) {
          const option = document.createElement('option');
          option.value = i;
          option.text = QUERY_TYPES[i].text;
          querySelect.add(option);
        }
        // Select the current query type
        querySelect.selectedIndex = node.queryType;

        // Show all relevant parameters to this query
        const queryTypeInfo = QUERY_TYPES[node.queryType];
        const params = queryTypeInfo.pathParams.concat(queryTypeInfo.queryParams);
        params.forEach((param) => {
          const divToShow = `#div-node-input-${param}`;
          $(divToShow).show();
        });

        // Set the document to hide/show elements for different query selections
        $(querySelect).data('prevQueryType', node.queryType);
        $(querySelect).change(function (data) {
          const newQueryType = $(this).val();
          const oldQueryType = $(this).data('prevQueryType');

          // Hide all parameters for old query type
          const oldInfo = QUERY_TYPES[oldQueryType];
          const oldParams = oldInfo.pathParams.concat(oldInfo.queryParams);
          oldParams.forEach((param) => {
            const divToHide = `#div-node-input-${param}`;
            $(divToHide).hide();
          });

          // Show all parameters for new query type
          const newInfo = QUERY_TYPES[newQueryType];
          const newParams = newInfo.pathParams.concat(newInfo.queryParams);
          newParams.forEach((param) => {
            const divToShow = `#div-node-input-${param}`;
            $(divToShow).show();
          });

          // If POST or PUT request, also show request body
          if (newInfo.method == 'POST' || newInfo.method == 'PUT') {
            $('#div-node-input-body').show();
          } else {
            $('#div-node-input-body').hide();
          }

          // Save the current query type
          $(this).data('prevQueryType', newQueryType);
        });

        // Show custom sortBy field
        const sortBySelect = document.getElementById('node-input-sortBy');
        $(sortBySelect).change(function (data) {
          if ($(this).val() == 'other') {
            $(`#div-node-input-sortByOther`).show();
          } else {
            $(`#div-node-input-sortByOther`).hide();
          }
        });

        // Convert JSON inputs to typedInput
        $('#node-input-body').typedInput({
          type: 'json',
          types: ['json'],
        });

        // Adds an editableList widget for the given parameter `p`
        // of the specified type `t`
        function addEditableTypedList(param, paramType) {
          // Creates a function to be called when adding a list item
          // for this parameter & type
          const getAddItem = function () {
            return function (container, i, data) {
              container.css({
                overflow: 'hidden',
                whiteSpace: 'nowrap',
              });
              const row = $('<div/>').appendTo(container);

              // Create the TypedInput element
              const typedInputElem = $('<input/>', {
                class: `node-input-${param}-value`,
                type: 'text',
                width: '100%',
              })
                .appendTo(row)
                .typedInput({
                  default: paramType,
                  types: [paramType],
                  type: paramType,
                })
                .typedInput('show');

              // Set the TypedInput element value
              if (data.value != undefined) {
                typedInputElem.typedInput('value', data.value);
              } else {
                // Use default value based on type
                switch (paramType) {
                  case 'str':
                    typedInputElem.typedInput('value', '');
                    break;
                  case 'json':
                    typedInputElem.typedInput('value', '{}');
                    break;
                }
              }
            };
          };

          // Create the editable list
          $(`#node-input-${param}-container`).editableList({
            addButton: true,
            height: 'auto',
            scrollOnAdd: true,
            sortable: true,
            removable: true,
            addItem: getAddItem(),
          });

          // Populate list with current values
          node[param].forEach((v) => {
            const value = paramType == 'json' ? JSON.stringify(v) : v;
            $(`#node-input-${param}-container`).editableList('addItem', { value });
          });
        }

        // Add editableList widget for list parameters
        addEditableTypedList('field', 'str');
        addEditableTypedList('filters', 'json');
        addEditableTypedList('sortOptions', 'json');
      },
      oneditsave: function () {
        const node = this;

        // Saves values in EditableList to the node config
        function saveListValues(param, paramType) {
          const entries = $(`#node-input-${param}-container`).editableList('items');
          node[param] = [];
          entries.each(function (e) {
            // Iterate through list items in UI
            const entry = $(this);
            const entryValue = entry.find(`.node-input-${param}-value`).val();
            switch (paramType) {
              // Push non-empty values
              case 'str':
                if (entryValue != '') {
                  node[param].push(entryValue);
                }
                break;
              case 'json':
                if (entryValue != '{}') {
                  node[param].push(JSON.parse(entryValue));
                }
                break;
            }
          });
          // Overwrite the node's config
          this[param] = node[param];
        }

        // Save list parameters
        saveListValues('field', 'str');
        saveListValues('filters', 'json');
        saveListValues('sortOptions', 'json');
      },
    });
  })();
</script>

<script type="text/html" data-template-name="tulip-tables">
  <div class="form-row">
    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
    <input type="text" id="node-input-name" placeholder="Name" />
  </div>
  <div class="form-row">
    <label for="node-input-apiAuth"
      ><i class="fa fa-user-circle"></i> Tulip API Authentication</label
    >
    <input id="node-input-apiAuth" />
  </div>
  <div class="form-row">
    <label for="node-input-keepAlive"> HTTP Options</label>
    <input
      type="checkbox"
      id="node-input-keepAlive"
      autocomplete="off"
      style="margin-left:10px; vertical-align:top; width:auto"
    />
    <label for="node-input-keepAlive" style="width:auto">Enable Connection Keep-Alive</label>
  </div>
  <div class="form-row" id="div-node-input-keepAliveMsecs" hidden>
    <label for="node-input-keepAliveMsecs">&nbsp;</label>
    <span style="width:auto">Keep-Alive Initial Delay (ms)</span>
    <input
      type="number"
      min="0"
      step="1"
      id="node-input-keepAliveMsecs"
      value="10000"
      style="width:auto"
    />
  </div>
  <br>
  <div class="form-row">
    <label for="node-input-retainMsgProps"> Output</label>
    <input
      type="checkbox"
      id="node-input-retainMsgProps"
      autocomplete="off"
      style="margin-left:10px; vertical-align:top; width:auto"
    />
    <label for="node-input-retainMsgProps" style="width:auto">Retain Input Message Properties</label>
  </div>
  <br>
  <div class="form-row">
    <label for="node-input-queryType"> Query Type</label>
    <select id="node-input-queryType" style="width:70%"></select>
  </div>
  <hr />
  <label style="width:100%;">
    <h4>Query Options</h4>
  </label>
  <div class="form-row" id="div-node-input-includeDeleted" hidden>
    <input
      type="checkbox"
      id="node-input-includeDeleted"
      autocomplete="off"
      style="margin-left:10px; vertical-align:top; width:auto"
    />
    <label for="node-input-includeDeleted" style="width:auto">Include deleted tables</label>
  </div>
  <div class="form-row" id="div-node-input-includeTotalCount" hidden>
    <input
      type="checkbox"
      id="node-input-includeTotalCount"
      autocomplete="off"
      style="margin-left:10px; vertical-align:top; width:auto"
    />
    <label for="node-input-includeTotalCount" style="width:auto">Include total count</label>
  </div>
  <div class="form-row" id="div-node-input-allowRecordsInUse" hidden>
    <input
      type="checkbox"
      id="node-input-allowRecordsInUse"
      autocomplete="off"
      style="margin-left:10px; vertical-align:top; width:auto"
    />
    <label for="node-input-allowRecordsInUse" style="width:auto">Allow records in use</label>
  </div>
  <div class="form-row" id="div-node-input-tableId" hidden>
    <label for="node-input-tableId"> Table ID</label>
    <input type="text" id="node-input-tableId" placeholder="tableId" />
  </div>
  <div class="form-row" id="div-node-input-queryId" hidden>
    <label for="node-input-queryId"> Query ID</label>
    <input type="text" id="node-input-queryId" placeholder="queryId" />
  </div>
  <div class="form-row" id="div-node-input-recordId" hidden>
    <label for="node-input-recordId"> Record ID</label>
    <input type="text" id="node-input-recordId" placeholder="recordId" />
  </div>
  <div class="form-row" id="div-node-input-aggregationId" hidden>
    <label for="node-input-aggregationId"> Aggregation ID</label>
    <input type="text" id="node-input-aggregationId" placeholder="aggregationId" />
  </div>
  <div class="form-row" id="div-node-input-fieldId" hidden>
    <label for="node-input-fieldId"> Field ID</label>
    <input type="text" id="node-input-fieldId" placeholder="fieldId" />
  </div>
  <div class="form-row" id="div-node-input-function" hidden>
    <label for="node-input-function"> Aggregation Function</label>
    <select id="node-input-function" style="width:70%;">
      <option value="sum" selected>Sum</option>
      <option value="count">Count</option>
      <option value="avg">Average</option>
      <option value="min">Minimum</option>
      <option value="max">Maximum</option>
      <option value="mode">Mode</option>
    </select>
  </div>
  <div id="div-node-input-sortBy" hidden>
    <div class="form-row">
      <label for="node-input-sortBy"> Sort By</label>
      <select id="node-input-sortBy" style="width:70%;">
        <option value="_sequenceNumber" selected>Sequence Number</option>
        <option value="_updatedAt">Updated At</option>
        <option value="_createdAt">Created At</option>
        <option value="other">(choose table field)</option>
      </select>
    </div>
    <div class="form-row" id="div-node-input-sortByOther" hidden>
      <label for="node-input-sortByOther">&nbsp;</label>
      <span style="width:70%">
        <span style="padding-right:2px; width:auto;">Table Field:</span>
        <input type="text" id="node-input-sortByOther" style="width:auto;" />
      </span>
    </div>
  </div>
  <div class="form-row" id="div-node-input-sortDir" hidden>
    <label for="node-input-sortDir"> Sort Direction</label>
    <select id="node-input-sortDir" style="width:70%;">
      <option value="asc" selected>Ascending</option>
      <option value="desc">Descending</option>
    </select>
  </div>
  <div class="form-row" id="div-node-input-sortOptions" hidden>
    <label for="node-input-sortOptions">Sort Options</label>
    <ol id="node-input-sortOptions-container"></ol>
  </div>
  <div class="form-row" id="div-node-input-filters" hidden>
    <label for="node-input-filters">Filters</label>
    <ol id="node-input-filters-container"></ol>
  </div>
  <div class="form-row" id="div-node-input-filterAggregator" hidden>
    <label for="node-input-filterAggregator">Filter Aggregator</label>
    <select id="node-input-filterAggregator" style="width:70%;">
      <option value="all" selected>all</option>
      <option value="any">any</option>
    </select>
  </div>
  <div class="form-row" id="div-node-input-limit" hidden>
    <label for="node-input-limit"> Limit</label>
    <input type="number" min="0" step="1" id="node-input-limit" value="10" />
  </div>
  <div class="form-row" id="div-node-input-offset" hidden>
    <label for="node-input-offset"> Offset</label>
    <input type="number" min="0" step="1" id="node-input-offset" value="0" />
  </div>
  <div class="form-row" id="div-node-input-field" hidden>
    <label for="node-input-field">Fields</label>
    <ol id="node-input-field-container"></ol>
  </div>
  <div id="div-node-input-body">
    <hr />
    <label style="width:100%;">
      <h4>Request Body Options</h4>
    </label>
    <div class="form-row">
      <label for="node-input-body"> Request Body</label>
      <input type="text" id="node-input-body" />
    </div>
  </div>
</script>

<script type="text/html" data-help-name="tulip-tables">
  <p>Reads & manipulates data in Tulip Tables using the Tulip Tables API.</p>

  <h3>Inputs</h3>
  <dl class="message-properties">
    <dt class="optional">
      body
      <span class="property-type">JSON</span>
    </dt>
    <dd>
      If the query type is a POST or PUT request, the body of the request. Overrides the data
      in the "Request Body" field.
    </dd>
    <dt class="optional">
      headers
      <span class="property-type">JSON</span>
    </dt>
    <dd>
      HTTP headers to include in the request. If a POST or PUT request, the header "Content-Type"
      will be set to "application/json" and will override <code>msg.headers["Content-Type"]</code>.
    </dd>
    <dt class="optional">
      [parameter]
    </dt>
    <dd>
      Any parameter of a Tulip Tables API request can be set by the input <code>msg.[parameter]</code>.
      The message value overrides the parameter value set by the node configuration.
    </dd>
  </dl>

  <h3>Outputs</h3>
  <ol class="node-ports">
      <dl class="message-properties">
        <dt>response <span class="property-type">JSON</span></dt>
        <dd>The HTTP response object from the API request.</dd>
        <dt>payload</dt>
        <dd>The parsed response body.</dd>
      </dl>
  </ol>

  <h3>Overview</h3>
  <p>Each <code>tulip-tables</code> node is configured to send data to a Tulip Tables API endpoint. On an input message, the
    node will send the configured request and output the HTTP response along with any returned data. The "Query Type" field
    determines the type of request, relevant parameters, and the response data type. See the Tulip Tables API documentation
    for more information on the different types of requests.
  </p>
  <p>
    To send data to a given factory instance, you must configure a <code>tulip-api-auth</code> node with authentication details.
    The API token used for authentication must have the appropriate permissions: either <code>tables:read</code>, <code>tables:write</code>,
    <code>table-queries:read</code>, or <code>table-queries:write</code>, depending on the type of request. This authentication node
    can be shared between multiple nodes that require Tulip API authentication.</p>

  <h3>Advanced Operation</h3>
  <p>
    The Tulip Tables API request parameters are specified in the node configuration. However, all parameters can also be specified by the
    input <code>msg</code>, and this value will dynamically override the static parameter value in the node configuration. For example,
    if you the "Table ID" field set to <code>id1</code> but send an input with <code>msg.tableId=id2</code>, the request will set parameter
    <code>tableId</code> to <code>id2</code>. The parameters <code>sortOptions</code> and <code>filters</code> can be set by the <code>msg</code>,
    and the request body (if a POST or PUT request) can be set by <code>msg.body</code>.
  </p>
  <p>
    Select "Retain Input Message Properties" to keep all properties of the input message in the output message, otherwise they will be cleared.
    If an input message property conflicts with a property set by this node (ex: <code>msg.response</code>) then the input message property
    will be overwritten.
  </p>
  <p>
    You can configure the HTTP agent to use keep-alive by checking "Enable Connection Keep-Alive" (default=<code>true</code>),
    and set the agent keepAliveMsecs (default=<code>10000ms</code>). Note that this sets the keep-alive behaviour of the HTTP agent,
    which is different than setting the "Connection": "Keep-Alive" HTTP header (which can be set through <code>msg.headers</code>).
  </p>

  <h3>References</h3>
  <ul>
    <li><a href=https://support.tulip.co/en/articles/2835889-an-overview-of-tables>
      <b>Overview of Tulip Tables</b>
    </a></li>
    <li><a href=https://support.tulip.co/en/articles/3983173-how-to-use-the-table-api>
      <b>How to Use the Table API</b>
    </a></li>
    <li>
      <b>Tulip API Documentation:</b> available at <a>https://[your-factory-url]/apiDocs</a>, see Tulip Tables endpoints.
    </li>
  </ul>
</script>