Java Testing Tool Users Manual

Owned by Teresa Rael (Unlicensed)
Last updated: Mar 03, 2017 by David Lewton (Unlicensed)
12 min read

Information

We are still working on migrating the project / documentation from the internal project name of Gambit to Cogswell / Cogs. They are one and the same.


The Java Testing Tool App is a convenient way to quickly test sending and receiving campaign messages from the Cogswell app.  The Java Testing Tool allows the user to send events through the Cogswell app that emulate real world events and can be used to test Segment and Campaign Rules logic.  The user can test with the Java Testing Tool alone or set up the iOS Test App, Android Test App or the C++ Test App in conjunction with the Java Testing Tool to test receiving messages on any device.

Before using the Java Testing Tool the user should have already created API Keys, set up a Namespace and Attributes through the Cogswell QuickStart wizard, created a Segment and created a Campaign. See the Cogswell UI Users Manual for instructions and information on using the Cogswell app.

Download the Java Testing Tool App

  1. Download the Java Testing Tool App from /wiki/spaces/GAM/pages/5767397
  2. Move the 'exampleapp' files someplace that is convenient to access on your computer
  3. Open a terminal session
  4. Navigate to where the example app is located, inside of the /bin/ directory.  Example = /Users/trael/Documents/Aviata/2015_2016_Gambit/exampleapp-1.0/bin/exampleapp
  5. Run ./exampleapp in your terminal window
  6. The Java Testing Tool will open in a new window, see image below.
  7. The Java Test Tool will log error and debugging information to the file Java.log in the directory in which it was opened.
  8. The Java Testing Tool runs on Java version 1.8 or higher.
  9. If you receive error messages, this means your Java version is out of date.
  10. In your terminal window run $ java -version:  to check the Java version that is currently installed.
  11. If your Java version is out of date see /wiki/spaces/GAM/pages/5767397 page, Common problems, for updating your Java version. 

When the Java Testing Tool App is installed and the app window is displayed, the user can set up the Java Testing Tool to interface with the Cogswell App. 

Java Testing Tool Set Up

Setup Tab

Entering the API Keys on this tab allows the Java Testing Tool to interface with the users account information in the Cogswell App

  1. Copy API Keys from the Cogswell App to Java Test Tool

    1. Cogswell App → General Setup → Keys

  2. Copy the Access Key and the Secret Key to the appropriate fields

  3. Check "Remember keys" checkbox to have the Java Testing Tool remember these keys from session to session.

Generate Client Key Tab

To add a layer of security the Client Keys are generated in conjunction with the users API Keys. The Client Keys Pair are the keys that are safe to include in the users public facing app.

  1. Click Generate Client Keys button
  2. Client Salt and Client Secret keys will be generated

Subscriptions Tab

 The Subscription tab allows the user to subscribe to and receive campaign messages for a specific 'Topic'. 

  1. Click the "Copy from previous tab" button to populate the Client Salt and the Client Secret Keys that were previously generated.
  2. Enter the Namespace that was previously created in the Cogswell App, for example = Demo_Namespace
  3. Enter a Topic Description - this can be any value that the user specifies. Create a Topic Description that will help to identify what Topic is being tested.
  4. Click the 'New' button. The Java Testing Tool will use the API Keys and the Namespace values to locate the users account in the Cogswell App and populate the Attributes associated with the Namespace. 
  5. The Namespace Attributes will populate the window, the Primary Key(s) will be checked.
  6. Enter a value for the 'Primary Key' Attribute(s)
  7. NOTE: Tab or click off of the Primary Key(s) Value field, the Subscription will not be sent if the cursor is in the Value field
  8. Click the 'Save' button
  9. The newly created Subscription will be displayed in the 'Subscription' list.
  10. The user can 'Subscribe' to as many Subscriptions as necessary for testing.

Send Events Tab

This tab allows the user to mock up event data by populating the values for the Namespace Attributes associated with the specified Namespace.  The user can send event data to test Segment logic and test Campaign Rules logic.   

  1. Click the "Copy from previous tab" button to populate the Client Salt and the Client Secret Keys that were previously generated.
  2. With the Timestamp feature the user can specify a precise timestamp if needed for testing or the user can check 'Use current timestamp' for general testing.
  3. Enter the Namespace that was previously created in the Cogswell App, for example = Demo_Namespace
  4. Select a Debug Directive from the drop down list,
    1. 'No-debug-directive' will run events through the Cogswell App Segments and Campaign Rules. Use this value for real life testing, use in conjuntion with the iOS, Android or C++ App to receive campaign messages on a device. 
    2. 'echo-as-message' will by-pass the Segments and Campaign Rules set up in the Cogswell App. Use this value for quickly testing connections between your app and Cogswell.
  5. Enter Event Name - this can be any value that the user specifies. Create an Event Name that will help to identify what is being tested.
  6. Click the 'Populate' button. The Java Testing Tool will use the API Keys and the Namespace values to locate the users account in the Cogswell App and populate the Attributes associated with the Namespace. 
  7. The Namespace Attributes will populate the window, the Primary Key will be checked.
  8. Enter a valid value in the Primary Key field(s) 
  9. Enter valid values in the Attribute field(s) that will trigger the campaign
  10. Click the 'Send Event' button

Received Messages Tab

This tab will display a list of  events that successfully passed through the Cogswell App. Received Messages are the result of generating events from the 'Send Events' tab, interfacing with the Cogswell App and returning a successful message.

  1. The 'Date Received' field will display the timestamp of the message as is related to the Timestamp field that was previously defined on the 'Send Event' tab.  
  2. The 'Event Name' field will display the Event Name that was previously defined on the 'Send Event' tab.  The Event Name can be changed to reflect what Event or Campaign is being tested at that time.
  3. The Campaign Name field will populate with the Campaign Name being tested
  4. Click on the Message entry to reveal the message data in the window below 

Random UUID Tab

A Version 4 UUID is a universally unique identifier that is generated using random numbers. This service is available for you to use to securely generate version 4 UUIDs to use for whatever purpose fits your business need. 

  1. Click the 'Generate' button to generate a UUID

View the PDF file below to walk through setting up and sending events from the Java Testing Tool



 

 

 

Testing With The Java Testing Tool

To test Segment and Campaign Rule logic using the Java Testing Tool, the user needs to 1) define a Mobile App in the Cogswell App, 2) install and set up a Testing App on a device. 

  1. Create A Mobile App in the Cogswell App

    1. Navigate to General setup → Mobile Applications

    2. Enter an Application ID, the user has previously set up this Bundle ID when the APNS Certificate was created.

    3. Select a Platform from the drop down list for testing - iOS / Android

    4. Select an Application Environment from the drop down list - Production / Development

      1. If Platform iOS is selected the Application Environment must be Production

    5. If Platform iOS is selected add a Cert File

      1. Click on the Choose file button and navigate to where the APNS Certificate is located on your computer, for information on create APNS certificates, see http://quickblox.com/developers/How_to_create_APNS_certificates

      2. Enter the Cert Password

    6. If Platform Android is selected, the user will enter their Android App API Key. For more information on creating Android App API Keys see https://developers.google.com/maps/documentation/android-api/start#step_1_download_android_studio

    7. Click 'Create Application" button and the New Mobile app will appear in the list below

  2.  Set up the iOS Testing App on an iPhone 
    1. Download the Cogs Demo App from the App Store
    2. Install the Cogs Demo App
    3. Send email to the iPhone in this format, replace xxxxx with access key, client salt and the client secret

gambitdemo://?access_key=xxxxx&client_salt=xxxxx&client_secret=xxxxx

      1. Access key comes from Gambit Keys
      2. Client salt and secret keys come from testing tool
    2. Open the email that was sent to the iPhone
    3. Copy the entire gamitdemo link in the email and paste the link into the URL field in Safari and click 'Go'
    4. The iOS Testing App will ask to open, click 'open'
    5. The app will open to the About page for a few seconds and then the Start page will be displayed automatically
    6. Click on the Subscription link
    7. The three Key fields will be populated, Access Key, Client Salt, Client Secret
    8. Enter the Application ID, this is the same ID that was used when defining the Mobile App in the Cogswell App
    9. Enter the Namespace Name associated with the Campaign that is being tested
    10. The Device Token field is automatically filled in with the devices unique token
    11. In the JSON section, there is an example of json string format that the user can modify for testing, be sure to delete "Attributes as JSON for example" 
    12. From the Subscription page the user will subscribe to a specific 'Topic', this is the same procedure when subscribing to a Topic in the Java Testing Tool 
    13. In the json string section enter the Primary Key Attribute(s) and value(s)
      1. example 

{ "customer_id" : 66 ,

"email_address" : "email@domain.com" }

    1. Click Register button to Subscribe to the Topic and Register the device
    2. Response back from the Testing tool API should be 'request processed successfully'
    3. Click 'OK' 

View the PDF file below to walk through setting up the iOS App and Subscribing to a Topic

 


Set up Java Testing Tool For Testing with iOS App

  1. Subscribe to the 'Topic' that corresponds to the Campaign that will be tested
    1. Click on the 'Subscriptions' tab
    2. Click the "Copy from previous tab" button to populate the Client Salt and the Client Secret Keys that were previously generated.
    3. Enter the Namespace that was previously created in the Cogswell App, for example = Demo_Namespace
    4. Enter a Topic Description - this can be any value that the user specifies. Create a Topic Description that will help to identify what Topic is being tested.
    5. Click the 'New' button. The Java Testing Tool will use the API Keys and the Namespace values to locate the users account in the Cogswell App and populate the Attributes associated with the Namespace. 
    6. The Namespace Attributes will populate the window, the Primary Key(s) will be checked.
    7. Enter a value for the 'Primary Key' Attribute(s)
    8. NOTE: Tab or click off of the Primary Key(s) Value field, the Subscription will not be sent if the cursor is in the Value field
    9. Click the 'Save' button
    10. The newly created Subscription will be displayed in the 'Subscription' list.

  2. Send an Event to be added to the Segment that corresponds to the Campaign being tested
    1. Click on the 'Send Events' tab
    2. Click the "Copy from previous tab" button to populate the Client Salt and the Client Secret Keys that were previously generated.
    3. With the Timestamp feature the user can specify a precise timestamp if needed for testing or the user can check 'Use current timestamp' for general testing.
    4. Enter the Namespace that was previously created in the Cogswell App, for example = Demo_Namespace
    5. Select 'No debug directive' as the Debug Directive to send event results to the iPhone
    6. Enter Event Name - this can be any value that the user specifies. Create an Event Name that will help to identify what is being tested.
    7. Click the 'Populate' button. The Java Testing Tool will use the API Keys and the Namespace values to locate the users account in the Cogswell App and populate the Attributes associated with the Namespace. 
    8. The Namespace Attributes will populate the window, the Primary Key will be checked.
    9. Enter a valid value in the Primary Key field(s) 
    10. Enter valid values in the Attribute field(s) that will trigger the Segment rules to add the test event to the Segment
    11. Click the 'Send Event' button
    12. The Segment count in the Cogwell App will increase by 1

  3. Send an Event to trigger the Campaign 
    1. Stay on the Send Events tab
    2. Select 'No debug directive' as the Debug Directive
    3. Update the Event Name field to correspond to what is being tested
    4. Enter a valid value in the Primary Key field(s) 
    5. Enter valid values in the Attribute field(s) that will trigger the campaign
    6. Click the 'Send Event' button
    7. Watch the iPhone to make sure that the expected content from the Campaign was received.


View the PDF file below to walk through sending events from the Java Testing Tool


 

Set up Java Testing Tool For Testing Connections with Cogswell

Use this testing option to quickly test that API Keys and a Namespace are set up properly and that a connection with Cogswell is valid.  This testing option does not evaluate Segments or Campaign Rules. 

  1. Subscribe to the 'Topic' that corresponds to the Campaign that will be tested
    1. Click on the 'Subscriptions' tab
    2. Click the "Copy from previous tab" button to populate the Client Salt and the Client Secret Keys that were previously generated.
    3. Enter the Namespace that was previously created in the Cogswell App, for example = Demo_Namespace
    4. Enter a Topic Description - this can be any value that the user specifies. Create a Topic Description that will help to identify what Topic is being tested.
    5. Click the 'New' button. The Java Testing Tool will use the API Keys and the Namespace values to locate the users account in the Cogswell App and populate the Attributes associated with the Namespace. 
    6. The Namespace Attributes will populate the window, the Primary Key(s) will be checked.
    7. Enter a value for the 'Primary Key' Attribute(s)
    8. NOTE: Tab or click off of the Primary Key(s) Value field, the Subscription will not be sent if the cursor is in the Value field
    9. Click the 'Save' button

  2. Send an Event to test the connection with Cogswell
    1. Click on the 'Send Events' tab
    2. Click the 'Copy from previous tab' to populate the Client Salt and the Client Secret keys
    3. With the Timestamp feature the user can specify a precise timestamp if needed for testing or the user can check 'Use current timestamp' for general testing.
    4. Enter the Namespace that is being tested
    5. Select 'echo-as-message' as the Debug Directive from the drop down list
    6. Enter Event Name - this can be any value that the user specifies. Create an Event Name that will help to identify what is being tested.
    7. Click the 'Populate' button. The Java Testing Tool will use the API Keys and the Namespace values to locate the users account in the Cogswell App. 
    8. The Namespace Attributes will populate the window, the Primary Key will be checked.
    9. Enter a valid value in the Primary Key field(s) 
    10. Tab or click off of the Primary Key Value field, the Event will not send if the cursor is in the value field.
    11. Click the 'Send Event' button
    12. The event data will update the window below
    13. Verify that the message was processed successfully and the timestamp was updated

  3. Check Received Messages Tab
    1. Click on the 'Received Messages' tab
    2. If an 'echo-as-test-mesage' was successfully sent to Cogswell and returned there will be an entry listed in the Received Messages list
    3. Verify that the 'echo-as-message' test was received, the newest events are put to the top of the list
    4. A successful 'echo-as-test-mesage' will show "NO-CAMPAIGN-FOR-ECHOED-EVENT' in the Campaign Name field. 

      View the PDF file below to walk through the 'echo-as-message' test


 

Set Up The iOS App To Send And Receive Message On An iPhone

  1. Set up the iOS Testing App on an iPhone 
    1. Download the Cogs Demo App from the App Store
    2. Install the Cogs Demo App
    3. Send email to the iPhone in this format, replace [xxxxx] with access key, client salt and the client secret

gambitdemo://?access_key=[xxxxx]&client_salt=[xxxxx]&client_secret=[xxxxx]

      1. Access key comes from Gambit Keys

      2. Client salt and secret keys come from testing tool

    2. Open and email that was went to the iPhone

    3. Copy the gamitdemo link in the email and paste the link into the URL in Safari

    4. The iOS Testing App will open to the About page

    5. The Start Page will be displayed automatically

    6. Click on the Subscription link

    7. The three Keys fields will be populated, Access Key, Client Salt, Client Secret.

    8. Enter the Application ID, this is the same ID that was used when defining the Mobile App in the Cogswell App

    9. Enter the Namespace Name associated with the Campaign that is being tested

    10. The Device Token is automatically filled in with the devices unique token

    11. In the JSON section, there is an example of json string format that the user can modify for testing, be sure to delete "Attributes as JSON for example" 


  2. Subscribe to a Topic
    1. From the Subscription page the user will subscribe to a specific 'Topic', this is the same procedure used when subscribing to a Topic in the Java Testing Tool 
    2. In the json string section enter the Primary Key Attribute(s) and value(s)
    3. example
      1. { "customer_id" : 66 ,
      2. "email_address" : "email@domain.com" }
    4. Click Register button to Subscribe to the Topic and Register the device
    5. Response back from the Testing Tool API should be 'request processed successfully'
    6. Click 'OK' 

      View the PDF file below to walk through the steps to set up the iOS app and Subscribe to a Topic



  1. Join A Segment
    1. Click 'Start' to go back to start menu
    2. Click 'Event'
    3. The Access key and Clients keys and Namespace fields will be filled in
    4. Enter the Campaign Name, example Opt_In_Campaign
    5. Enter Event Name, this can be anything you want, create a name that will help to identify what you are testing
    6. In the json string section enter the Primary Key / value and the attributes / values to join the Segment
      1. example { "customer_id" : 1 , "state" : "nm" }
    7. In the Cogswell App navigate to the Namespace Segment page and notice the Namespace Segment count for the Segment that is being tested. If this is a brand new Segment the count should be 0
    8. On the phone, click 'Execute' to send an event to join the Segment
    9. Refresh the Cogswell Segment list and verify that the count increased to 1

  2. Send An Event To Receive A Campaign From Phone
    1. From the Event page update the Event Name field that will help to identify what is being tested
      1. example = Demo_Namespace_Receive_Campaign
    2. Update the json string section enter the Primary Key / value and the attributes / values to trigger the Campaign
      1. example { "customer_id" : 1 , "state" : "nm" , "opt_in_status" : 1 }
    3. Click Execute
    4. A success message from the API will be displayed with the message payload on the iPhone.