[Alerting] Documentation for how to pre-configure connectors.

docs/user/alerting/action-types.asciidoc

@@ -34,14 +34,23 @@ a| <<webhook-action-type, Webhook>>
 
 [NOTE]
 ==============================================
-Some action types are paid commercial features, while others are free. 
-For a comparison of the Elastic subscription levels, 
-see https://www.elastic.co/subscriptions[the subscription page]. 
+Some action types are paid commercial features, while others are free.
+For a comparison of the Elastic subscription levels,
+see https://www.elastic.co/subscriptions[the subscription page].
 ==============================================
 
+[float]
+[[create-connectors]]
+=== Connectors
+
+You can create connectors for actions in <<managing-alerts-and-actions, Alerts and Actions>> or via the action API.
+For out-of-the-box and standardized connectors, you can <<pre-configured-connectors, preconfigure connectors>>
+before {kib} starts.
+
 include::action-types/email.asciidoc[]
 include::action-types/index.asciidoc[]
 include::action-types/pagerduty.asciidoc[]
 include::action-types/server-log.asciidoc[]
 include::action-types/slack.asciidoc[]
 include::action-types/webhook.asciidoc[]
+include::pre-configured-connectors.asciidoc[]

docs/user/alerting/pre-configured-connectors.asciidoc

@@ -0,0 +1,88 @@
+[role="xpack"]
+[[pre-configured-connectors]]
+
+== Preconfigured connectors
+
+You can preconfigure an action connector to have all the information it needs prior to startup
+by adding it to the `kibana.yml` file.
+Sensitive configuration information, such as credentials, can use the {kib} keystore.
+
+Preconfigured connectors offer the following capabilities:
+
+- Require no setup. Configuration and credentials needed to execute an
+action are predefined, including the connector name and ID.
+- Appear in all spaces because they are not saved objects.
+- Cannot be edited or deleted.
+
+[float]
+[[preconfigured-connector-example]]
+=== Example of a preconfigured connector
+
+The following example shows a valid configuration 2 out-of-the box connector.
+
+[source,console]
+------------------------
+  xpack.actions.preconfigured:
+    - id: 'my-slack1'           <1>
+      actionTypeId: .slack      <2>
+      name: 'Slack #xyz'        <3>
+      config:                   <4>
+        webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz'
+    - id: 'webhook-service'
+      actionTypeId: .webhook
+      name: 'Email service'
+      config:
+        url: 'https://email-alert-service.elastic.co'
+        method: post
+        headers:
+          header1: value1
+          header2: value2
+      secrets:                  <5>
+        user: elastic
+        password: changeme
+------------------------
+
+<1> `id` is the action connector identifier.
+<2> `actionTypeId` is the action type identifier.
+<3> `name` is the name of the preconfigured connector.
+<4> `config` is the action type specific to the configuration.
+<5> `secrets` is sensitive configuration, such as username, password, and keys.
+
+[NOTE]
+==============================================
+Sensitive properties, such as passwords, can also be stored in the {kib} keystore.
+==============================================
+
+[float]
+[[pre-configured-connector-alert-form]]
+=== Creating an alert with a preconfigured connector
+
+When attaching an action to an alert,
+select from a list of available action types, and
+then select the Slack or Webhook type. Those action types were configured previously.
+The preconfigured connector is installed and is automatically selected.
+
+[role="screenshot"]
+image::images/alert-pre-configured-slack-connector.png[Create alert with selected Slack action type]
+
+The dropdown is populated with additional preconfigured Slack connectors.
+The `preconfigured` label distinguishes them from space-aware connectors that use saved objects.
+
+[role="screenshot"]
+image::images/alert-pre-configured-connectors-dropdown.png[Dropdown list with pre-cofigured connectors]
+
+[float]
+[[managing-pre-configured-connectors]]
+=== Managing preconfigured connectors
+
+Preconfigured connectors appear in the connector list, regardless of which space the user is in.
+They are tagged as “preconfigured” and cannot be deleted.
+
+[role="screenshot"]
+image::images/pre-configured-connectors-managing.png[Connectors managing tab with pre-cofigured]
+
+Clicking on a preconfigured connector shows the description, but not any of the configuration.
+A message indicates that this is a preconfigured connector.
+
+[role="screenshot"]
+image::images/pre-configured-connectors-view-screen.png[Pre-configured connector view details]

x-pack/plugins/triggers_actions_ui/public/application/sections/action_connector_form/action_form.test.tsx

@@ -232,7 +232,7 @@ describe('action_form', () => {
         Object {
           "id": "test2",
           "key": "test2",
-          "label": "Test connector 2 (pre-configured)",
+          "label": "Test connector 2 (preconfigured)",
         },
       ]
       `);

x-pack/plugins/triggers_actions_ui/public/application/sections/action_connector_form/action_form.tsx

@@ -152,7 +152,7 @@ export const ActionForm = ({
   const preconfiguredMessage = i18n.translate(
     'xpack.triggersActionsUI.sections.actionForm.preconfiguredTitleMessage',
     {
-      defaultMessage: '(pre-configured)',
+      defaultMessage: '(preconfigured)',
     }
   );
   const getSelectedOptions = (actionItemId: string) => {

x-pack/plugins/triggers_actions_ui/public/application/sections/action_connector_form/connector_edit_flyout.test.tsx

@@ -96,13 +96,13 @@ describe('connector_edit_flyout', () => {
     expect(connectorNameField.first().prop('value')).toBe('action-connector');
   });
 
-  test('if pre-configured connector rendered correct in the edit form', () => {
+  test('if preconfigured connector rendered correct in the edit form', () => {
     const connector = {
       secrets: {},
       id: 'test',
       actionTypeId: 'test-action-type-id',
       actionType: 'test-action-type-name',
-      name: 'pre-configured-connector',
+      name: 'preconfigured-connector',
       isPreconfigured: true,
       referencedByCount: 0,
       config: {},

x-pack/plugins/triggers_actions_ui/public/application/sections/action_connector_form/connector_edit_flyout.tsx

@@ -104,7 +104,7 @@ export const ConnectorEditFlyout = ({
           />
            
           <EuiBetaBadge
-            label="Pre-configured"
+            label="Preconfigured"
             data-test-subj="preconfiguredBadge"
             tooltipContent={i18n.translate(
               'xpack.triggersActionsUI.sections.preconfiguredConnectorForm.tooltipContent',
@@ -197,7 +197,7 @@ export const ConnectorEditFlyout = ({
             <EuiLink href="https://www.elastic.co/guide" target="_blank">
               <FormattedMessage
                 id="xpack.triggersActionsUI.sections.editConnectorForm.preconfiguredHelpLabel"
-                defaultMessage="Learn more about pre-configured connectors."
+                defaultMessage="Learn more about preconfigured connectors."
               />
             </EuiLink>
           </Fragment>

x-pack/plugins/triggers_actions_ui/public/application/sections/actions_connectors_list/components/actions_connectors_list.tsx

@@ -215,7 +215,7 @@ export const ActionsConnectorsList: React.FunctionComponent = () => {
                   label={i18n.translate(
                     'xpack.triggersActionsUI.sections.alertForm.preconfiguredTitleMessage',
                     {
-                      defaultMessage: 'Pre-configured',
+                      defaultMessage: 'Preconfigured',
                     }
                   )}
                   tooltipContent="This connector can't be deleted."

x-pack/test/functional_with_es_ssl/apps/triggers_actions_ui/connectors.ts

@@ -185,7 +185,7 @@ export default ({ getPageObjects, getService }: FtrProviderContext) => {
       expect(searchResultsAfterDelete.length).to.eql(0);
     });
 
-    it('should not be able to delete a pre-configured connector', async () => {
+    it('should not be able to delete a preconfigured connector', async () => {
       const preconfiguredConnectorName = 'xyz';
       await pageObjects.triggersActionsUI.searchConnectors(preconfiguredConnectorName);
 
@@ -196,7 +196,7 @@ export default ({ getPageObjects, getService }: FtrProviderContext) => {
       expect(await testSubjects.exists('preConfiguredTitleMessage')).to.be(true);
     });
 
-    it('should not be able to edit a pre-configured connector', async () => {
+    it('should not be able to edit a preconfigured connector', async () => {
       const preconfiguredConnectorName = 'xyz';
 
       await pageObjects.triggersActionsUI.searchConnectors(preconfiguredConnectorName);