Merge pull request IBMStreams#41 from ddebrunner/doc_03

Improve docs and update to 0.3.

com.ibm.streamsx.slack/com.ibm.streamsx.slack.services/message.spl

@@ -13,41 +13,43 @@ use com.ibm.streamsx.topology::String ;
 use com.ibm.streamsx.topology.topic::Subscribe ;
 
 /**
- * Microservice sending messages to a Slack incoming webhook.
+ * Microservice sending messages to a Slack incoming web hook.
  *
  * Subscribes to `Json` topic and sends each JSON tuple as-is
- * as the request body to the webhook. Any application can
- * thus send messages to the Slack webhook by publishing a JSON
+ * as the request body to the web hook. Any application can
+ * thus send messages to the Slack web hook by publishing a JSON
  * message to the topic this microservice is subscribing to.
  *
- * The JSON can have any properties accepted by the webhook
+ * The JSON can have any properties accepted by the web hook
  * minimally having `text` property defining the text of the message.
  *
  * Additionally the topic with type `String` is subscribed to allowing
  * applications to publish simple text messages using the `String` schema.
- * Each tuple is converted to a JSON object for the webhook with
+ * Each tuple is converted to a JSON object for the web hook with
  * a single property `text` with the value of the tuple.
  *
- * Slack incoming webhooks are described here:  [https://api.slack.com/incoming-webhooks]
+ * Slack incoming web hooks are described here:  [https://api.slack.com/incoming-webhooks]
  *
  * **Microservice topic**
  *
  * The topic subscribed to is set by the submission time parameter `topic`
- * defaulting to `streamsx/slack/messages`.
+ * defaulting to `streamsx/slack/messages`. The subscribed types are:
+ * * [Json] - Each JSON object is the message body.
+ * * [String] - Each string is the message text to send.
  * 
  * **Slack webhook URL**
  *
  * The Slack incoming webhook is defined by the `slackUrl` property in
  * a Streams application configuration. The name of the application
- * configuration is set by the submission time parameter `applicationConfigurationName` defaulting to `slackConfiguration`.
+ * configuration is set by the submission time parameter `slackConfiguration` defaulting to `slack`.
  *
- * @param  slack Name of the application configuration containing the `slackUrl` property. Defaults to the submission time parameter `slack` which in turn defaults to `slack`.
+ * @param  slackConfiguration Name of the application configuration containing the `slackUrl` property. Defaults to the submission time parameter `slackConfiguration` which in turn defaults to `slack`.
  * @param topic Topic name service subscribes.  Defaults to the submission time parameter `topic` which in turn defaults to `streamsx/slack/messages`.
  */
 public composite SlackMessageService
 {
 	param
-		expression<rstring> $slack : getSubmissionTimeValue("slack", "slack");
+		expression<rstring> $slackConfiguration : getSubmissionTimeValue("slackConfiguration", "slack");
 		expression<rstring> $topic : getSubmissionTimeValue("topic", "streamsx/slack/messages");
 
 	graph
@@ -79,6 +81,6 @@ public composite SlackMessageService
 		() as SendMessage = SendSlackMessage(JsonMessages, TextAsJson)
 		{
 			param
-				applicationConfigurationName : $slack ;
+				slackConfiguration : $slackConfiguration ;
 		}
 }

com.ibm.streamsx.slack/com.ibm.streamsx.slack.services/namespace-info.spl

@@ -0,0 +1,15 @@
+// ****************************************************************************
+// * Copyright (C) 2018, International Business Machines Corporation          *
+// ****************************************************************************
+
+/**
+ * Slack microservices.
+ *
+ * Microservices provide ready to use Streams applications
+ * that can be comined to build a complete applications.
+ *
+ * [SendSlackMessage] supports sending tuples to a Slack channel
+ * through an incoming web hook.
+*/
+
+namespace com.ibm.streamsx.slack.services;

com.ibm.streamsx.slack/com.ibm.streamsx.slack/namespace-info.spl

@@ -0,0 +1,12 @@
+// ****************************************************************************
+// * Copyright (C) 2018, International Business Machines Corporation          *
+// ****************************************************************************
+
+/**
+ * Interaction with Slack.
+ *
+ * [SendSlackMessage] supports sending tuples to a Slack channel
+ * through an incoming web hook.
+*/
+
+namespace com.ibm.streamsx.slack;

com.ibm.streamsx.slack/com.ibm.streamsx.slack/types.spl

@@ -9,14 +9,12 @@ namespace com.ibm.streamsx.slack;
  */
 type Message = tuple<rstring text>;
 
-/**
- * Slack message with emoji.
- * Extends [Message] to add the `icon_emoji` attribute to
- * specify the emoji of the message.
- */
-type EmojiMessage = Message, tuple<rstring icon_emoji>;
-
 /**
  * Standard JSON schema.
 */
 type Json = tuple<rstring jsonString>;
+
+/**
+ * Standard String schema.
+*/
+type String = tuple<rstring string>;

com.ibm.streamsx.slack/impl/java/src/com/ibm/streamsx/slack/SendSlackMessage.java

@@ -50,14 +50,18 @@
 		)
 @InputPorts({
 	@InputPortSet(
-			description="Each tuple is converted to JSON and sent as a message to the "
-			        + "Slack incoming Webhook. The schema must include a ", 
+          description="Each tuple is converted to JSON and sent as a message to the "
+            + "Slack incoming web hook.\\n\\n"
+            + "The port's schema must be one of:\\n"
+            + " * [Json] - Streams standard JSON schema. Each tuple represents a JSON object and is used as the message contents. This allows the application to use any field supported by the Slack web hook.\\n"
+            + " * A single `rstring` or `ustring` attribute (which includes the default string exchange schema [String]). The value of the string is used as the `text` property in the JSON message object.\\n"
+            + " * A schema containing an attribute named `text` with type `rstring` or `ustring`. The value of the `text` attributed is used as the `text` property in the JSON message object. [Message] type may be used to augment other schemas.\\n",
+
 			cardinality=1, 
 			optional=false, 
 			windowingMode=WindowMode.NonWindowed, 
 			windowPunctuationInputMode=WindowPunctuationInputMode.Oblivious)})
 @Libraries({
-	// Include javax.mail libraries.
 	"opt/downloaded/*"
 	})
 public class SendSlackMessage extends TupleConsumer {
@@ -68,10 +72,17 @@ public class SendSlackMessage extends TupleConsumer {
 	// ------------------------------------------------------------------------
 
 	protected static final String DESC_OPERATOR = 
-			"Sends messages to a Slack incoming WebHook."
+			"Sends messages to a Slack incoming web hook."
 		  + "\\n"
-		  + "Each incoming tuple results in a message sent to the incoming Webhook."
-		  + "The tuple is converted to JSON and sent to the incoming Webhook.";
+		  + "Each incoming tuple results in a message sent to the incoming web hook."
+		  + "The tuple is converted to JSON and sent to the incoming web hook."
+                  + "\\n\\n"
+                  + "This operator forms the basis for the [SlackMessageService] microservice."
+                  + "\\n\\n"
+                  + "Guide on Slack incoming web hooks: [https://api.slack.com/incoming-webhooks]\\n"
+
+
+        ;
 
 	@ContextCheck(runtime=false)
 	public static void validateSchema(OperatorContextChecker checker) {
@@ -123,18 +134,17 @@ private static boolean isStringAttribute(StreamSchema schema) {
 
 	@Parameter(
 			optional=true,
-			description="Specifies the Slack incoming WebHook URL to send messages to."
+			description="Specifies the Slack incoming web hook URL to send messages to."
 			)
 	public void setSlackUrl(String slackUrl) throws IOException {
 		this.slackUrl = slackUrl;
 	}
 
 	@Parameter(
 			optional=true,
-			description="Name of application configuration containing operator parameters. "
-					  + "Parameters of type Attribute should be specified in the form of a String."
+			description="Name of application configuration containing operator parameters. The incoming web hook URL can be set in the application configuration by setting the `slackUrl` property. This is more flexible than the operator parameter as the incoming web hook URL can be changed while the application is running."
 			)
-	public void setApplicationConfigurationName(String applicationConfigurationName) throws IOException {
+	public void setSlackConfiguration(String applicationConfigurationName) throws IOException {
 		if (!applicationConfigurationName.isEmpty()) {
 			this.applicationConfigurationName = applicationConfigurationName;
 		}

com.ibm.streamsx.slack/info.xml

@@ -3,8 +3,12 @@
  xmlns:info="http://www.ibm.com/xmlns/prod/streams/spl/toolkitInfo">
  <info:identity>
    <info:name>com.ibm.streamsx.slack</info:name>
-   <info:description></info:description>
-   <info:version>0.2.0</info:version>
+   <info:description>Integration with Slack digital workspace.
+
+   Typical use is to send alerts or informational messages from
+   a Streams application to Slack channel using a incoming web hook.
+   </info:description>
+   <info:version>0.3.0</info:version>
    <info:requiredProductVersion>4.2.0.0</info:requiredProductVersion>
  </info:identity>
  <info:dependencies/>