GUACAMOLE-926: Add file format help page.

guacamole/src/main/frontend/src/app/import/styles/help.css

@@ -0,0 +1,60 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+.import.help {
+
+    text-transform: none;
+
+}
+
+.import.help p {
+
+    max-width: 70em;
+
+}
+
+.import.help h2 {
+
+    padding-top: 0px;
+    padding-bottom: 0px;
+
+}
+
+.import.help p, .import.help pre {
+
+    margin-left: 1em;
+
+}
+
+.import.help pre {
+
+    background-color: rgba(0,0,0,0.15);
+    padding: 10px;
+    width: fit-content;
+
+}
+
+.import.help .footnotes {
+
+    border-top: 1px solid gray;
+    padding-top: 1em;
+    width: fit-content;
+    margin-left: 1em;
+    
+}

guacamole/src/main/frontend/src/app/import/templates/connectionImportFileHelp.html

@@ -0,0 +1,93 @@
+<div class="import help">
+
+    <div class="header">
+        <h2>{{'CONNECTION_IMPORT.HELP_HEADER' | translate}}</h2>
+        <guac-user-menu></guac-user-menu>
+    </div>
+
+    <h2>{{'CONNECTION_IMPORT.HELP_FILE_TYPE_HEADER' | translate}}</h2>
+    <p>{{'CONNECTION_IMPORT.HELP_FILE_TYPE_DESCRIPTION' | translate}}</p>
+
+    <h2>{{'CONNECTION_IMPORT.HELP_CSV_HEADER' | translate}}</h2>
+    <p>{{'CONNECTION_IMPORT.HELP_CSV_DESCRIPTION' | translate}}</p>
+    <p>{{'CONNECTION_IMPORT.HELP_CSV_MORE_DETAILS' | translate}}</p>
+    <pre>name,protocol,hostname,group,users,groups,guacd-encryption (attribute)
+conn1,vnc,conn1.web.com,ROOT,guac user 1;guac user 2,Connection 1 Users,none
+conn2,rdp,conn2.web.com,ROOT/Parent Group,guac user 1,,ssl
+conn3,ssh,conn3.web.com,ROOT/Parent Group/Child Group,guac user 2;guac user 3,,
+conn4,kubernetes,,,,,</pre>
+
+    <h2>{{'CONNECTION_IMPORT.HELP_JSON_HEADER' | translate}}</h2>
+    <p>{{'CONNECTION_IMPORT.HELP_JSON_DESCRIPTION' | translate}}</p>
+    <p>{{'CONNECTION_IMPORT.HELP_JSON_MORE_DETAILS' | translate}}</p>
+    <pre>[
+  {
+    "name": "conn1",
+    "protocol": "vnc",
+    "parameters": { "hostname": "conn1.web.com" },
+    "parentIdentifier": "ROOT",
+    "users": [ "guac user 1", "guac user 2" ],
+    "groups": [ "Connection 1 Users" ],
+    "attributes": { "guacd-encryption": "none" }
+  },
+  {
+    "name": "conn2",
+    "protocol": "rdp",
+    "parameters": { "hostname": "conn2.web.com" },
+    "group": "ROOT/Parent Group",
+    "users": [ "guac user 1" ],
+    "attributes": { "guacd-encryption": "none" }
+  },
+  {
+    "name": "conn3",
+    "protocol": "ssh",
+    "parameters": { "hostname": "conn3.web.com" },
+    "group": "ROOT/Parent Group/Child Group",
+    "users": [ "guac user 2", "guac user 3" ],
+  },
+  {
+    "name": "conn4",
+    "protocol": "kubernetes",
+  }
+]</pre>
+
+    <h2>{{'CONNECTION_IMPORT.HELP_YAML_HEADER' | translate}}</h2>
+    <p>{{'CONNECTION_IMPORT.HELP_YAML_DESCRIPTION' | translate}}</p>
+    <pre>---
+  - name: conn1
+    protocol: vnc
+    parameters:
+      hostname: conn1.web.com
+    group: ROOT
+    users:
+    - guac user 1
+    - guac user 2
+    groups:
+    - AWS EC2 Administrators
+    attributes:
+      guacd-encryption: none
+  - name: conn2
+    protocol: rdp
+    parameters:
+      hostname: conn2.web.com
+    group: ROOT/Parent Group
+    users:
+    - guac user 1
+    attributes:
+      guacd-encryption: none
+  - name: conn3
+    protocol: ssh
+    parameters:
+      hostname: conn3.web.com
+    group: ROOT/Parent Group/Child Group
+    users:
+    - guac user 2
+    - guac user 3
+  - name: conn4
+    protocol: kubernetes</pre>
+
+    <ol class="footnotes">
+        <li>{{'CONNECTION_IMPORT.HELP_SEMICOLON_FOOTNOTE' | translate}}</li>
+    </ol>
+
+</div>

guacamole/src/main/frontend/src/app/import/templates/connectionImportFileUpload.html

@@ -3,7 +3,7 @@
     <div class="upload-header">
         <span class="file-options">{{'CONNECTION_IMPORT.UPLOAD_FILE_TYPES' | translate}}</span>
         <a
-            href="#/import/upload-help"
+            href="#/import/connection/file-format-help" target="_blank"
             class="file-help-link">{{'CONNECTION_IMPORT.UPLOAD_HELP_LINK' | translate}}
         </a>
     </div>

guacamole/src/main/frontend/src/app/index/config/indexRouteConfig.js

@@ -135,6 +135,14 @@ angular.module('index').config(['$routeProvider', '$locationProvider',
             resolve       : { updateCurrentToken: updateCurrentToken }
         })
 
+        // Connection import page
+        .when('/import/connection/file-format-help', {
+            title         : 'APP.NAME',
+            bodyClassName : 'settings',
+            templateUrl   : 'app/import/templates/connectionImportFileHelp.html',
+            resolve       : { updateCurrentToken: updateCurrentToken }
+        })
+
         // Management screen
         .when('/settings/:dataSource?/:tab', {
             title         : 'APP.NAME',

guacamole/src/main/frontend/src/translations/en.json

@@ -191,6 +191,24 @@
 
         "HEADER": "Connection Import",
 
+        "HELP_HEADER": "Connection Import File Format",
+
+        "HELP_FILE_TYPE_HEADER": "File Types",
+        "HELP_FILE_TYPE_DESCRIPTION" : "Three file types are supported for connection import: CSV, JSON, and YAML. The same data may be specified by each file type. This must include the connection name and protocol. Optionally, a connection group location, a list of users and/or user groups to grant access, connection parameters, or connection protocols may also be specified.",
+
+        "HELP_CSV_HEADER": "CSV Format",
+        "HELP_CSV_DESCRIPTION": "A connection import CSV file has one connection record per row. Each column will specify a connection field. At minimum the connection name and protocol must be specified.",
+        "HELP_CSV_MORE_DETAILS": "The CSV header for each row specifies the connection field. The connection group ID that the connection should be imported into may be directly specified with \"parentIdentifier\", or the path to the parent group may be specified using \"group\" as shown below. In most cases, there should be no conflict between fields, but if needed, an \" (attribute)\" or \" (parameter)\" suffix may be added to disambiguate. Lists of user or user group identifiers must be semicolon-seperated.¹",
+
+        "HELP_JSON_HEADER": "JSON Format",
+        "HELP_JSON_DESCRIPTION": "A connection import JSON file is a list of connection objects. At minimum the connection name and protocol must be specified in each connection object.",
+        "HELP_JSON_MORE_DETAILS": "The connection group ID that the connection should be imported into may be directly specified with a \"parentIdentifier\" field, or the path to the parent group may be specified using a \"group\" field as shown below. An array of user and user group identifiers to grant access to may be specified per connection.",
+
+        "HELP_YAML_HEADER": "YAML Format",
+        "HELP_YAML_DESCRIPTION": "A connection import YAML file is a list of connection objects with exactly the same structure as the JSON format.",
+        
+        "HELP_SEMICOLON_FOOTNOTE": "If needed, semicolons can be escaped with a backslash, e.g. \"first\\\\;last\"",
+
         "ERROR_AMBIGUOUS_CSV_HEADER": 
             "Ambiguous CSV Header \"{HEADER}\" could be either a connection attribute or parameter",
         "ERROR_ARRAY_REQUIRED":