DOC-4949 Refine attributes in Streaming Learning (#54)

* token steps

* token stuff and attributes pt 1

* rest of attributes

* support-url

* astra-db

Author: aimurphy

antora.yml

@@ -8,13 +8,22 @@ nav:
 
 asciidoc:
   attributes:
+    company: 'DataStax'
     product: 'Astra Streaming'
+    product-short: 'Astra'
+    astra-db: 'Astra DB'
+    astra-ui: 'Astra Portal'
+    astra-url: 'https://astra.datastax.com'
+    astra-ui-link: '{astra-url}[{astra-ui}^]'
     pulsar: 'Apache Pulsar'
     pulsar-short: 'Pulsar'
     pulsar-reg: 'Apache Pulsar(TM)'
     pulsar-version: '2.10' #DO NOT INCLUDE PATCH VERSION <MAJOR>.<MINOR>.<PATCH>
     debezium-version: '1.7'
     astra-streaming-examples-repo: 'https://raw.githubusercontent.com/datastax/astra-streaming-examples/master'
+    kafka-for-astra: 'Starlight for Kafka'
+    starlight-rabbitmq: 'Starlight for RabbitMQ'
     cass: Apache Cassandra
     cass-short: Cassandra
-    cass-reg: Apache Cassandra(R)
+    cass-reg: Apache Cassandra(R)
+    support-url: 'https://support.datastax.com'

modules/ROOT/pages/index.adoc

@@ -45,20 +45,20 @@ xref:streaming-learning:use-cases-architectures:starlight/jms/index.adoc[Get sta
 ****
 
 [sidebar.landing-card]
-.xref:streaming-learning:use-cases-architectures:starlight/kafka/index.adoc[Starlight for Kafka]
+.xref:streaming-learning:use-cases-architectures:starlight/kafka/index.adoc[{kafka-for-astra}]
 ****
 --
-Starlight for Kafka brings native {pulsar} protocol support by introducing a Kafka protocol handler on {pulsar-short} brokers.
+{kafka-for-astra} brings native {pulsar} protocol support by introducing a Kafka protocol handler on {pulsar-short} brokers.
 
 xref:streaming-learning:use-cases-architectures:starlight/kafka/index.adoc[Get started now] | xref:starlight-for-kafka:ROOT:index.adoc[Configuring] | https://github.com/datastax/starlight-for-kafka[Source Code]
 --
 ****
 
 [sidebar.landing-card]
-.xref:streaming-learning:use-cases-architectures:starlight/rabbitmq/index.adoc[Starlight for RabbitMQ]
+.xref:streaming-learning:use-cases-architectures:starlight/rabbitmq/index.adoc[{starlight-rabbitmq}]
 ****
 --
-Starlight for RabbitMQ combines the AMQP 0.9.1 API with {pulsar-short}, providing a powerful way to modernize your RabbitMQ infrastructure, improve performance, and reduce costs.
+{starlight-rabbitmq} combines the AMQP 0.9.1 API with {pulsar-short}, providing a powerful way to modernize your RabbitMQ infrastructure, improve performance, and reduce costs.
 
 xref:streaming-learning:use-cases-architectures:starlight/rabbitmq/index.adoc[Get started now] | xref:starlight-for-rabbitmq:ROOT:index.adoc[Configuring] | https://github.com/datastax/starlight-for-rabbitmq[Source Code]
 --

modules/functions/pages/astream-functions.adoc

@@ -115,7 +115,7 @@ The command below assumes you've properly configured the client.conf file for pu
 bin/pulsar-admin functions create --function-config-file </absolute/path/to/your/python/func-create-config.yml>
 ----
 
-. Check results: Go to the {astra_ui} to see your newly deployed function listed under the “Functions” tab for your Tenant. See <<controlling-your-function,Controlling your function>> for more information on testing and monitoring your function in {product}.
+. Check results: Go to the {astra-ui} to see your newly deployed function listed under the “Functions” tab for your Tenant. See <<controlling-your-function,Controlling your function>> for more information on testing and monitoring your function in {product}.
 
 .. You can also use the pulsar-admin command to list your functions:
 +
@@ -249,7 +249,7 @@ userConfig:
 +
 [NOTE]
 ====
-{product} requires the “inputs” topic to have a message schema defined before deploying the function. Otherwise, deployment errors may occur. Use the {astra_ui} to define the message schema for a topic.
+{product} requires the “inputs” topic to have a message schema defined before deploying the function. Otherwise, deployment errors may occur. Use the {astra-ui} to define the message schema for a topic.
 ====
 +
 . Use pulsar-admin to deploy your new JAR to {product} or {pulsar-short}.
@@ -260,7 +260,7 @@ The command below assumes you've properly configured the client.conf file for pu
 bin/pulsar-admin functions create --function-config-file  </absolute/path/to/your/javajar/func-create-config.yml>
 ----
 
-. Check results: Go to the {astra_ui} to see your newly deployed function listed under the “Functions” tab for your Tenant. See <<controlling-your-function,Controlling your function>> for more information on testing and monitoring your function in {product}.
+. Check results: Go to the {astra-ui} to see your newly deployed function listed under the “Functions” tab for your Tenant. See <<controlling-your-function,Controlling your function>> for more information on testing and monitoring your function in {product}.
 
 .. You can also use the pulsar-admin command to list your functions:
 +
@@ -280,7 +280,7 @@ image::astream-name-function.png[Function and Namespace]
 
 . Select the file you want to pull the function from and which function you want to use within that file.
 
-Astra generates a list of acceptable classes. Python and Java functions are added a little differently from each other.
+{product} generates a list of acceptable classes. Python and Java functions are added a little differently from each other.
 
 Python functions are added by loading a Python file (.py) or a zipped Python file (.zip). When adding Python files, the Class Name is specified as the name of the Python file without the extension plus the class you want to execute.
 

modules/functions/pages/deploy-in-sink.adoc

@@ -8,7 +8,7 @@ Now, functions can be deployed at sink creation and apply preprocessing to sink
 
 == Create sink function in {product}
 
-Creating a sink function is similar to creating a sink in the {astra_ui}, but with a few additional steps.
+Creating a sink function is similar to creating a sink in the {astra-ui}, but with a few additional steps.
 
 . xref:pulsar-io:connectors/index.adoc[Create a sink] as described in the {product} documentation.
 . During sink creation, select the transform function you want to run inside the sink.

modules/functions/partials/deploy-as.adoc

@@ -1,6 +1,6 @@
-Deploy transform functions in the *Functions* tab of the {astra_ui}.
+Deploy transform functions in the *Functions* tab of the {astra-ui}.
 
-The process is similar to xref:astra-streaming:developing:astream-functions.adoc[creating a function in the {astra_ui}], but with a few additional steps.
+The process is similar to xref:astra-streaming:developing:astream-functions.adoc[creating a function in the {astra-ui}], but with a few additional steps.
 
 . After naming your new function, select the *Use {company} transform function* option. 
 . Select a transform function from the list of available functions:

modules/pulsar-io/pages/connectors/index.adoc

@@ -28,7 +28,7 @@ include::partial$connectors/sources/source-connectors.adoc[tag=production]
 
 {company} is always experimenting with connectors. Below are the connectors currently in development that have not yet been promoted to official support in *{product}*.
 
-To get access to these connectors, contact {support_url}[{company} Support].
+To get access to these connectors, contact {support-url}[{company} Support].
 
 === Sink Connectors (experimental)
 
@@ -57,22 +57,32 @@ Assuming you have downloaded client.conf to the {pulsar-short} folder:
 ----
 --
 
-cURL::
+curl::
 +
 --
+// tag::rest-env-vars[]
+You need a {pulsar-short} token for REST API authentication.
+This is different from your {astra-db} application tokens.
+
+. In the {astra-ui-link}, go to *Streaming*, click your tenant's name, and then click the *Settings* tab.
 
-You'll need to create an {product} API token to be used with the Rest API. This is different from your Astra tokens.
+. Click *Create Token*.
 
-Navigate to the "Settings" area in the {product} UI and choose "Create Token".
+. Copy the token, store it securely, and then click *Close*.
 
-Retrieve the web service URL from the "Connect" tab in the {product} UI.
+. Click the *Connect* tab, and then copy the *Web Service URL*.
 
+. Create environment variables for your tenant's token and web service URL:
++
 [source,shell,subs="attributes+"]
 ----
 export WEB_SERVICE_URL=<replace-me>
 export ASTRA_STREAMING_TOKEN=<replace-me>
 ----
+// end::rest-env-vars[]
 
+. Use these values to form curl commands to the REST API:
++
 [source,shell,subs="attributes+"]
 ----
 curl "$WEB_SERVICE_URL/admin/v3/sinks/builtinsinks" -H "Authorization: $ASTRA_STREAMING_TOKEN"
@@ -100,18 +110,7 @@ Assuming you have downloaded client.conf to the {pulsar-short} folder:
 cURL::
 +
 --
-
-You'll need to create an {product} API token to be used with the Rest API. This is different from your Astra tokens.
-
-Navigate to the "Settings" area in the {product} UI and choose "Create Token".
-
-Retrieve the web service URL from the "Connect" tab in the {product} UI.
-
-[source,shell,subs="attributes+"]
-----
-export WEB_SERVICE_URL=<replace-me>
-export ASTRA_STREAMING_TOKEN=<replace-me>
-----
+include::pulsar-io:connectors/index.adoc[tag=rest-env-vars]
 
 [source,shell,subs="attributes+"]
 ----

modules/pulsar-io/pages/connectors/sinks/astra-db.adoc

@@ -1,11 +1,11 @@
-= {astra_db} ({cass-reg} enhanced)
+= {astra-db} ({cass-reg} enhanced)
 :connectorName: astra-db-sink
 :connectorType: astra-db
 :page-tag: astra-db,cdc,sink-connector
 
-{company} {astra_db} Sink Connector is based on the open-source https://docs.datastax.com/en/pulsar-connector/docs/index.html[{cass-reg} sink connector for {pulsar-reg}]. Depending on how you deploy the connector, it can be used to sink topic messages with a table in {astra_db} or a table in a {cass-short} cluster outside of DB.
+{company} {astra-db} Sink Connector is based on the open-source https://docs.datastax.com/en/pulsar-connector/docs/index.html[{cass-reg} sink connector for {pulsar-reg}]. Depending on how you deploy the connector, it can be used to sink topic messages with a table in {astra-db} or a table in a {cass-short} cluster outside of DB.
 
-The {product} portal provides simple way to connect this sink and a table in Astra DB with simply a token. Using pulsar-admin or the REST API, you can configure the sink to connect with a {cass-short} connection manually.
+The {product} portal provides simple way to connect this sink and a table in {astra-db} with simply a token. Using pulsar-admin or the REST API, you can configure the sink to connect with a {cass-short} connection manually.
 
 This reference assumes you are manually connecting to a {cass-short} table.
 
@@ -51,7 +51,7 @@ include::example$connectors/sinks/{connectorType}/config.csv[]
 // TODO: Need descriptions of every param
 === Auth Properties
 
-These values are provided in the *auth* area in the above cassandra connection parameters.
+These values are provided in the *auth* area in the above {cass-short} connection parameters.
 
 [%header,format=csv,cols="2,1,1,3"]
 |===
@@ -60,7 +60,7 @@ include::example$connectors/sinks/{connectorType}/auth.csv[]
 
 === Topic Properties
 
-These values are provided in the *topic* area in the above cassandra connection parameters.
+These values are provided in the *topic* area in the above {cass-short} connection parameters.
 
 Refer to the official documentation for a https://docs.datastax.com/en/pulsar-connector/docs/cfgRefPulsarDseConnection.html[connection properties reference].
 

modules/pulsar-io/partials/connectors/sinks/curl-tab.adoc

@@ -1,17 +1,24 @@
 // tag::curl-prereq[]
-You'll need to create an {product} API token to be used with the REST API. This is different from your Astra tokens. 
+You need a {pulsar-short} token for REST API authentication.
+This is different from your {astra-db} application tokens.
 
-Navigate to the "Settings" area in the {product} UI and choose "Create Token".
+. In the {astra-ui-link}, go to *Streaming*, click your tenant's name, and then click the *Settings* tab.
 
-Retrieve the web service URL from the "Connect" tab in the {product} UI.
+. Click *Create Token*.
 
-Refer to the complete https://pulsar.apache.org/sink-rest-api/#tag/sink[{pulsar-short} sinks REST API spec] for all available options.
+. Copy the token, store it securely, and then click *Close*.
+
+. Click the *Connect* tab, and then copy the *Web Service URL*.
 
+. Create environment variables for your tenant's token and web service URL:
++
 [source,shell,subs="attributes+"]
 ----
 export WEB_SERVICE_URL=<replace-me>
 export ASTRA_STREAMING_TOKEN=<replace-me>
 ----
++
+Refer to the complete https://pulsar.apache.org/sink-rest-api/#tag/sink[{pulsar-short} sinks REST API spec] for all available options.
 // end::curl-prereq[]
 // tag::curl-start[]
 [source,shell,subs="attributes+"]

modules/pulsar-io/partials/connectors/sources/curl-tab.adoc

@@ -1,18 +1,25 @@
 // tag::curl-prereq[]
-You'll need to create an {product} API token to be used with the REST API. This is different from your Astra tokens. 
+You need a {pulsar-short} token for REST API authentication.
+This is different from your {astra-db} application tokens.
 
-Navigate to the "Settings" area in the {product} UI and choose "Create Token".
+. In the {astra-ui-link}, go to *Streaming*, click your tenant's name, and then click the *Settings* tab.
 
-Retrieve the web service URL from the "Connect" tab in the {product} UI.
+. Click *Create Token*.
 
-Refer to the complete https://pulsar.apache.org/source-rest-api/#tag/sources[{pulsar-short} sources REST API spec],
-for all available options.
+. Copy the token, store it securely, and then click *Close*.
+
+. Click the *Connect* tab, and then copy the *Web Service URL*.
 
+. Create environment variables for your tenant's token and web service URL:
++
 [source,shell,subs="attributes+"]
 ----
 export WEB_SERVICE_URL=<replace-me>
 export ASTRA_STREAMING_TOKEN=<replace-me>
 ----
++
+Refer to the complete https://pulsar.apache.org/source-rest-api/#tag/sources[{pulsar-short} sources REST API spec],
+for all available options.
 // end::curl-prereq[]
 // tag::curl-start[]
 [source,shell,subs="attributes+"]

modules/pulsar-io/partials/connectors/sources/monitoring.adoc

@@ -16,19 +16,27 @@ include::example$connectors/sources/pulsar-admin-info.sh[]
 cURL::
 +
 --
+You need a {pulsar-short} token for REST API authentication.
+This is different from your {astra-db} application tokens.
 
-You'll need to create an {product} API token to be used with the REST API. This is different from your Astra tokens. 
+. In the {astra-ui-link}, go to *Streaming*, click your tenant's name, and then click the *Settings* tab.
 
-Navigate to the "Settings" area in the {product} UI and choose "Create Token".
+. Click *Create Token*.
 
-Retrieve the web service URL from the "Connect" tab in the {product} UI.
+. Copy the token, store it securely, and then click *Close*.
 
+. Click the *Connect* tab, and then copy the *Web Service URL*.
+
+. Create environment variables for your tenant's token and web service URL:
++
 [source,shell,subs="attributes+"]
 ----
 export WEB_SERVICE_URL=<replace-me>
 export ASTRA_STREAMING_TOKEN=<replace-me>
 ----
 
+. Use these values to form curl commands to the REST API:
++
 [source,shell,subs="attributes+"]
 ----
 include::example$connectors/sources/curl-info.sh[]
@@ -60,25 +68,33 @@ include::example$connectors/sources/pulsar-admin-status.sh[]
 cURL::
 +
 --
+You need a {pulsar-short} token for REST API authentication.
+This is different from your {astra-db} application tokens.
+
+. In the {astra-ui-link}, go to *Streaming*, click your tenant's name, and then click the *Settings* tab.
 
-You'll need to create an {product} API token to be used with the REST API. This is different from your Astra tokens. 
+. Click *Create Token*.
 
-Navigate to the "Settings" area in the {product} UI and choose "Create Token".
+. Copy the token, store it securely, and then click *Close*.
 
-Retrieve the web service URL from the "Connect" tab in the {product} UI.
+. Click the *Connect* tab, and then copy the *Web Service URL*.
 
+. Create environment variables for your tenant's token and web service URL:
++
 [source,shell,subs="attributes+"]
 ----
 export WEB_SERVICE_URL=<replace-me>
 export ASTRA_STREAMING_TOKEN=<replace-me>
 ----
 
+. Use these values to form curl commands to the REST API:
++
 [source,shell,subs="attributes+"]
 ----
 include::example$connectors/sources/curl-status.sh[]
 ----
 --
-
++
 Response::
 +
 --