Using advanced mode

Discovery connector request nodes provide an advanced mode capability that you can use during create actions. In the default edit view for an action, some applications have fields that are hidden because they are not needed for general use cases. For more advanced use cases, you can switch to advanced mode editing, which provides extra capabilities for editing flows. This topic describes the additional configuration that is required when you want to use advanced mode.

Before you begin

Install IBM® App Connect Enterprise 12.0.11.0 or later to use the advanced mode capability.

Check that in the IBM App Connect Enterprise Toolkit, you have a message flow that contains a request node for the discovery connector that you want to use. Configure it as described in the configuration topic for your chosen connector (such as Using Slack with IBM App Connect Enterprise). For example, the following message flow contains an HTTPInput node, a Slack Request node, and an HTTPReply node.

1. If the Connector Discovery wizard is running, close it by clicking the X in the upper-right corner of the window.
2. In the Properties view of the input node for your message flow, select the Basic tab. In the Path suffix for URL field, enter a value for the path suffix, for example /slack. (In this example, the input node is an HTTPInput node.)
3. In the Properties view of the input node for your message flow, select the Input message parsing tab. In the Message domain field, select JSON : For JavaScript Object Notation messages from the drop-down menu
4. Create a blank JSON schema as described in Creating a JSON schema file. Populate the JSON file with entries that relate to the action that you are performing in Connector Discovery. For example:
   slackmessage.schema.json

   
   {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object",
     "properties": {
       "destinationType": {
         "type": "string"
       },
       "objectId": {
         "type": "string"
       },
       "text": {
         "type": "string"
       },
       "parse": {
         "type": "string"
       },
       "messageAttachment": {
         "type": "object",
         "properties": {
           "messageText": {
             "type": "string"
           },
           "preText": {
             "type": "string"
           },
           "id": {
             "type": "integer"
           },
           "fallBack": {
             "type": "string"
           },
           "extracts": {
             "type": "string"
           }
         },
         "required": [
           "messageText",
           "preText",
           "id",
           "fallBack",
           "extracts"
         ]
       },
       "unfurlLinks": {
         "type": "boolean"
       },
       "unfurlMedia": {
         "type": "boolean"
       },
       "username": {
         "type": "string"
       },
       "asUser": {
         "type": "boolean"
       },
       "iconUrl": {
         "type": "string"
       },
       "iconEmoji": {
         "type": "string"
       },
       "threadTimestamp": {
         "type": "string"
       },
       "replyBroadcast": {
         "type": "boolean"
       }
     },
     "required": [
       "destinationType",
       "objectId",
       "text",
       "parse",
       "messageAttachment",
       "unfurlLinks",
       "unfurlMedia",
       "username",
       "asUser",
       "iconUrl",
       "iconEmoji",
       "threadTimestamp",
       "replyBroadcast"
     ]
   }

   For more information about creating JSON schemas, see json-schema.org.

5. In the Properties view of the request node, select the Request tab. Click Add to open the Add Map inputs entry wizard
6. Complete the following fields:
   • Input name: Choose a unique name for the Map Inputs table, for example HTTP_Input.
   • Input location: Click Browse and select $InputRoot/JSON/Data from the XPath Expression Builder.
   • Schema location: Click Browse to open the JSON Schema Selection wizard. Select the schema that you created in step 1.a.iv and click OK.
   • Schema root: The location in the schema file that describes the message structure. This value is only required if the JSON schema is not at the root of the schema document.
7. Click OK to save the entries.
8. Click Launch Connector Discovery to start the Connector Discovery wizard for the connector.
   In the "Send message" section, the field Destination type is displayed. The pre-defined options Channel, User, and Group are available from the drop-down menu.
9. Click Map options menu and select Switch to advanced mode.
   
   In the "Send message" section, the fields Destination type, and Object ID are displayed.
10. Optional: In the Controls section of the wizard, decide how you want to populate the target fields by selecting either Use input message unchanged or Define mappings below from the menu.
    The default setting is Define mappings below. If you select Define mappings below, additional target fields are available. The link Auto match fields is displayed. If you click Auto match fields, the fields are automatically populated with mappings that are derived from the entries in the JSON schema file that you created in step 4 and referenced from the request node in step 6.

You must populate the required fields, Destination type, Object ID, and the target field Text. (All the other target fields are optional).

11. Populate the required fields and the required target field Text by placing the cursor in the input field, clicking Insert a mapping, and selecting a mapping from the Available mappings table. The available mappings in the table are derived from the schema that you created in step 4 and referenced from the request node in step 6.

    Optionally, you can populate the fields manually by typing in the required values. For example, you can type the value channel in Destination type.

    Optionally, you can insert a function by clicking Insert a function and selecting a function from the Functions menu.

    

    For example, if you type HELLO WORLD in the Text field, you can select Insert a function > Functions > String functions > $lower case(). The text HELLO WORLD{{$lowercase(«string»)}} appears in the Text field. The incoming message HELLO WORLD is converted to hello world when it is sent to the destination.

    

    

Populate any optional target fields that you want to include

12. Optionally filter the target fields by inputting text into the search field. For example, if you type the text "User" into the search field, only the fields Username and As user appear in the list of target fields.
13. Populate any optional target fields that you want to include by placing the cursor in the target field. Text is displayed after the field to describe the purpose of the target field. Complete the target fields as described in the following list. The mappings in the Available mappings table are derived from the schema that you created in step 4 and referenced from the request node in step 6.
    The target fields are:

    1. Text: A message text to be sent. (Text is the only target field that is required. All other target fields are optional).
    2. Parse: Specifies how the message is parsed. By default, it is set to none. Click Insert a mapping, and select a mapping from the Available mappings table.
    3. Link names: Indicates whether to link channel names and usernames. Select True, False, or Custom. If you select Custom, click Insert a mapping, and select a mapping from the Available mappings table.
    4. Message attachments: The structured message attachments.
       The mapping for the Message attachments field must include child mappings for the fields Message text, Pre-text, ID, Fallback, and Extracts. In this example, the JSON schema that you created in step 4, includes the following section:

       
       "messageAttachment": {
             "type": "object",
             "properties": {
               "messageText": {
                 "type": "string"
               },
               "preText": {
                 "type": "string"
               },
               "id": {
                 "type": "integer"
               },
               "fallBack": {
                 "type": "string"
               },
               "extracts": {
                 "type": "string"
               }
            

       The following mappings are generated in the Available mappings table from the above section of the JSON schema file:
       
       Click Insert a mapping, and select a mapping from the Available mappings table. For this example, select the mapping messageAttachment.
    5. Message text: The attachment text to be sent. Click Insert a mapping, and select a mapping from the Available mappings table. For this example, select the child mapping messageText.
    6. Pre-text: The optional text that appears above the attachment block. Click Insert a mapping, and select a mapping from the Available mappings table. For this example, select the child mapping preText.
    7. ID: The identifier of an attachment. Click Insert a mapping, and select a mapping from the Available mappings table. For this example, select the child mapping iD.
    8. Fallback: The plain-text summary of the attachment. Click Insert a mapping, and select a mapping from the Available mappings table. For this example, select the child mapping fallBack.
    9. Extracts: The extracts for an attachment. Click Insert a mapping, and select a mapping from the Available mappings table. For this example, select the child mapping extracts.
    10. Unfurl links: Select True, False, or Custom. Select True to enable the unfurling of primarily text-based content. If you select Custom, click Insert a mapping, and select a mapping from the Available mappings table.
    11. Unfurl media: Select True, False, or Custom. Select False if you want to disable the unfurling of media content. If you select Custom, click Insert a mapping, and select a mapping from the Available mappings table.
    12. Username: The bot's username. This property is only applicable when you set the value of As user property to False. Click Insert a mapping, and select a mapping from the Available mappings table.
    13. As user: Select True, False, or Custom. Select True to post the message as the authenticated user, instead of as a bot. By default the value is set to False. If you select Custom, click Insert a mapping, and select a mapping from the Available mappings table.
    14. Icon URL: The URL to an image to use as the icon for the message. This property is only applicable when you set the value of As user property to False. Otherwise, it is ignored. Click Insert a mapping, and select a mapping from the Available mappings table.
    15. Icon emoji: The emoji to use as the icon for the message. If you set this value, it overrides the icon URL. This property is only applicable when you set the value of As user property to False. Click Insert a mapping, and select a mapping from the Available mappings table.
    16. Thread timestamp: Specify another message's timestamp value to make this message a reply. Click Insert a mapping, and select a mapping from the Available mappings table.
    17. Reply broadcast: The value in this field indicates whether a reply is made visible to everyone in the channel or conversation. The default value is false. You must use this property along with the Thread timestamp property. Select True, False, or Custom. If you select Custom, click Insert a mapping, and select a mapping from the Available mappings table.

    Optionally, you can populate the fields manually by typing in the required values. For example, you can type the value FRED in Username.

    Optionally, you can insert a function by clicking Insert a function and selecting a function from the Functions menu.

    

    For example, if you type FRED in the Username field, you can select Insert a function > Functions > String function > $lower case(). The text FRED{{$lowercase(«string»)}} appears in the Username field. The incoming message FRED is converted to fred when it is sent to the destination.

    For more information about Advanced mode, see Using Advanced mode editing in the IBM App Connect Enterprise as a Service documentation.
14. Optionally, you can edit the data that is associated with a mapping and preview your changes by completing the following steps:
    1. Place the cursor in a target field, for example, Username. By default, the text "SampleUsername" is displayed after the target field.
    2. Click Insert a mapping, and select a mapping from the Available mappings table, for example. username.
    3. In the "Send message" section, click the pencil icon to view available mappings and edit your sample data.
       
       The table "Map inputs and sample data" is displayed.
    4. In the table, select the mapping username and change the data "Sampleusername" to "Fred". The text "Fred" will be displayed after the Username target field.