Create A User Account

Register a new account

https://cogswell.io/#!/register

...

Note: all fields in Cogswell are case-sensitive

When all user information is entered, next answer the Captcha question and then click the 'Sign Up' button.  An email is sent to the email address entered asking the user to confirm the registration, "A confirmation message has been sent to your email address. Please confirm your registration, then login here."  Once the email is received the user is asked to activate the Cogswell account by clicking the link in the email.  Once the link is clicked the Cogswell account is now activate and the user is returned to the Cogswell login page. 

Login and Get Started

Fill in the 'Username' and 'Password' fields on this page. The 'Username' is the email address that was entered when creating an account.  Enter the Password that was created when creating an account. Then click the 'Login' button.

...

• Step 1: Generate an API Key

• • To create a Key Pair the user will enter a name in the Name field to identify the API Keys based on the users schema, this field is alphanumeric.
  • Then click the 'Create keys' button to generate a new set of Keys, an Access Key and a Secret Key. At the point the access key can be copied and used in an app or the user can finish the QuickStart process and retrieve the access key at a later time. 
  • Click the 'Next' button 
    

• Step 3: Create a Project

• • A Project is a logical organization of data. A Project typically represents a product line. Product lines have devices that are produced or have other devices they interact with. No matter what API Keys the user uses, the data sent to Cogswell will be organized in the system according to the Project associated with that data.
  • Enter a Project name in the field, use a name that will help organize data, this field is case-sensitive and accepts alphanumeric characters.
  • A Project is required to use Cogswell.
  • Click the 'Next' button

• Step 4: Create Project Attributes and Primary Key

  • Project Attributes are fields that are created to collect information for a specific Project.
  • Enter a name for the Attribute, this field is will accept alphanumeric characters and is case-sensitive.
  • Select the appropriate data type, Integer, Text, Float, Date or Boolean.
  • Click the '+Add Attribute' button.
  • Create as many Project Attributes as needed.  New Project Attributes can be created at any time, click the 'Project Attributes' link in the menu to go to the Project Attributes page.
  • Once all Project Attributes are created, select a Primary Key or Keys by clicking the checkbox associated with that Attribute.
  • Primary Keys are used to unique identify a device, or person, or whatever the unique identifying aspect of your Project is. This could correspond to a unique identification number of a customer, a device, or a combination of both. Two examples: (1) a user's email address (2) a device's UDID. Primary Keys(s) can be a single attribute or a combination of attributes. The Primary Key(s) will describe how data is organized so careful consideration should be given when defining a Primary Key or Keys. The Primary Key Attribute(s) can be Project specific, or come from the list of Core Attributes (Note: Core Attributes are a legacy feature that is no longer supported). Once created, the Primary Key(s) for a Project cannot be changed. 
    • Primary keys in combination with the Project are used to define a topic. This means you could have as many topics as you do unique primary key values.
  • Click the 'Next' button

• Step 5: Finish and Test

• • Click the 'I'm ready to go!' button to be directed to your account in the Cogswell site.

Getting Around in Cogswell

Getting around in Cogswell is pretty simple, here are some helpful hints.

...

• • 'Date' fields are sorted in chronological order and can be sorted by newest to oldest or oldest to newest.
• My Campaigns
  • The user can choose to which columns to display by clicking on the settings icon in the top right corner.
    • Campaign, Campaign ID, Start Date, Stop Date, Created, Status and Actions.
• Account
  
  • View your Account information by clicking on your user name in the upper right corner, then click Account. 

General Setup

API Keys

API Keys are the mechanism by which all communication with the Cogswell API is authenticated.

...

• API Key - Set of 2 Keys, KeyPair, that uniquely identifies your organization and associates any data sent to Cogswell to your account. The API Keys can be used for administrative tasks against the API, including generating new client keys. API Keys are required to use Cogswell.
• KeyPair - Unique set of identification strings that are used to authenticate events containing the associated Access Key, identify the user and Project events for billing.
             • Access Key - This is the key that is embed in your client application. 
             • Secret Key - This is used to authenticate events containing the associated Access Key. The Secret Key component of your API Keys should remain completely secret and secure in your internal systems and should NEVER be deployed into any client apps.

Client Keys

Client Keys are derived from API Keys. The user can select which API Key will be associated with the Client Keys. It is these Client Keys, not the API Keys, which should be deployed in those apps/devices which use the Cogswell API and the Cogswell SDKs. Client Keys are limited to those actions to which clients should be limited: sending events, establishing push WebSockets, etc.

...

This system allows greater control over how to authorize devices, systems, or applications to hit our APIs. This design means that if a Client Key is compromised and is being abused, the user can revoke access for certain Client Secret / Client Salt pairs without affecting other devices, apps, or systems. This means that the primary Secret Key can stay secure and can continue to be used. If we did not provide derived keys for clients, but instead only used the API Keys for everything, then the API Keys would have to be removed universally which would affect all devices, apps, or systems that used that API Key for Cogswell authentication.

Projects 

Projects are used to organize data that is sent to and from Cogswell.  A Project typically represents a product line. Product lines have devices that are produced or other devices they interact with. Everything in Cogswell operates at the Project level. The Project value will always be included in the data that is sent to and from Cogswell.  Reporting, dashboard, segments, campaigns, etc. will be organized by Project.

...

• Attribute Name – Can consist of Alphanumeric characters and underscores (_), this field does not accept spaces
• Data Type – Values are Integer, Text, Float, Date, Boolean

Mobile Applications

Create a Mobile Application that defines the mobile environment and Cert file or Android API Key associated with the users Mobile App.  Defining Mobile Applications is not required if a mobile app is not used.

...

If the Application Platform selected is Android, then the user must enter the Android API Key that the user has previously created. For more information on creating Android App API Keys see https://developers.google.com/maps/documentation/android-api/start#step_1_download_android_studio

My Campaigns

The My Campaigns page displays a list of Campaigns that the user has created for a specific Project, which is visible in the upper left corner. Selecting a different Project from the Project drop down list will display the campaigns created for that Project.

...

Clicking on the ‘Show status changes’ icon will display a pop up window with all changes to the status with a date and time stamp of the status change.

New Campaigns

New Campaigns can be created on this page. The 4-step wizard take the user step by step through the process to create a Campaign.  

• Step 1: OVERVIEW

• • Campaign Name – Enter the name of the Campaign, this field will accept all characters
  • Start campaign date/time

...

• • Click Next button to move to the Content tab.

• Step 2: CONTENT

  Campaign message content can utilize many options from a URL pointing to web-based content, Push notification message text, json payload, iOS APNS or Android GCM. Some of these fields have the ability to inject attribute values that are stored in the database.

  Injection into a field requires that you put an attribute name surrounded by double brackets and to be either prefixed with a "pub." or a "sub." Below is an example of what you may inject into a JSON attribute field:

  • Injection

    • Injection into a field requires that you put an attribute name surrounded by double brackets and to be either prefixed with a "pub." or a "sub." Below is an example of what you may inject into a JSON attribute field.

    • example:

      Code Block
      { {"message": "Congratulations {{sub.name}}! You are our {{pub.number}} customer!"} }

      • The above example assumes that we have attributes called "name" and "number".
      • The first attribute will be injected with the most recent value for that attribute for the CIID which is receiving the message.
      • The second attribute will be injected with the most recent value for that attribute for the person who triggered the campaign to send the message.
        • The event that triggered the message does not have to contain the injected attribute.
    • If the attribute does not exist in the double braces, then there will be no substitution and value will remain the same.
    • If the attribute does exist in the Project definition but has no value defined for that specific attribute the substitution will occur and will replace the text and double brackets with the text "null". 
      • The only exception to this rule is if there is a string that has no value defined in the JSON payload then it will be replaced with the empty string.
    • For the JSON body any strings injected that contain a double quote, the double quote will be escaped before it is inserted into the JSON
    • The fields that can use attribute substitution:
      • URL
      • Notification Message
      • JSON Payload
      • iOS - sound
      • iOS - category
      • Android - message title
      • Android - icon
      • Android - tag
      • Android - click action

  • Fields

    • URL

      • No URL - The user should select this option if the Campaign message content will not be a URL but will be one of the other options available on the page.  

      • Specify a URL - The user should select this option if the content is a URL, a  fill-in box will appear,  enter the URL here.  The URL fill-in box is required when this option is selected. The user will define how their client app will interpret the URL to take an action.

    • Notification Message  - Enter the Campaign message text here.  This text will appear as a push notification. 

    • Send Triggering Event - (On/Off switch) - Whichever event triggers this campaign will be forwarded into the message that is delivered the campaign's audience. The entire event dataset will be included in the campaign message.

    • JSON Payload - Enter Campaign message json payload string here. The user will define how their client app will interpret the JSON to take an action.

    • iOS Specific - APNS - The user should select this option to define Payload Keys. Refer to official APNS documentation here.

      • Content Available (On/Off switch) - Provide this key with a value of 1 to indicate that new content is available. Including this key and value means that when your app is launched in the background or resumed,application:didReceiveRemoteNotification:fetchCompletionHandler: is called.

      • If the notification is delivered when the app isn’t running in the foreground the system presents the notification, displaying an alert, badging an icon, perhaps playing a sound, and perhaps displaying one or more action buttons for the user to tap.

      • Badge -  The number to display as the badge of the app icon. If this property is absent, the badge is not changed. To remove the badge, set the value of this property to 0.

      • Sound - The user can specify a custom sound that iOS plays when it presents a local or remote notification for an app. The name of a sound file in the app bundle or in the Library/Sounds folder of the app’s data container. The sound in this file is played as an alert. If the sound file doesn’t exist or default is specified as the value, the default alert sound is played.

      • Category - Provide this key with a string value that represents the identifier property of the category identifier that you created to define custom actions. When iOS sees a push notification with a category key, it looks up the categories that were registered by the app. If iOS finds a match, it displays the corresponding actions with the notification

    • Android Specific - GCM - The user should specify the UI information and actions for a notification. NOTE: If you plan to send push notifications to an Android device you must check the 'Android Specific - GCM' checkbox. Refer to official GCM documentation here.

      • Notification Message Title - The user should enter the push notification message in this text box.  Cogswell will set the default value to match the 'Notification Message'.

      • Icon - The user should enter the custom icon name in this text box to set the custom icon.  The custom icon should have previously defined. Cogswell will set a default value.

      • Click Action - The user should always define the action that's triggered when the user clicks the notification; usually this action opens an Activity in your application. The user can also add buttons to the notification that perform additional actions, If the user uses additional action buttons, the user must also make their functionality available in an Activity in the app.

    • Click Next button to move to the Audience tab.

• Step 3: AUDIENCE

  Define which users, events or devices will receive a Campaign.

  • Show to

    • Whomever triggers this Campaign - Click box, default value.  Selecting this option will show the Campaign to any user, event or device that meets the criteria defined in the Campaign Rules section.  

    • Include Segments - Drop down list of all previously defined Segments for a specific Project - The user can select 1 or more Segments of users, events or devices that will be eligible to receive the Campaign.

...

• • Click Next button to move to the Rules tab.

• Step 4: RULES

  Define the Campaign triggering criteria by creating Rules, this functionality is similar to creating Segments to define a group of users, events or devices.

  • Rules- The user can create 1 or more Rules using Event Ranges, Event Filters, Attribute Filters and Attribute Conditions

    • No rules needed - By selecting this option the Campaign criteria will be based on the Audience that was defined for this Campaign in the previous tab. 

    • Rule description - The user can define a name for a Rule based on the user's own schema. This field will accept alpha-numberic characters.

...

• • • Once the user has created as many Event, Attribute Filters and/or Conditions, the user then clicks the '+Add Rule' button to create a triggering Rule for the Campaign.  The user can create as many Rules as necessary.  All Rules will will de displayed in the Rules list.
    • When the user is satisfied that all triggering Rules have been created, the user clicks the 'Finish' button to save all options and create the Campaign.

Project Attributes

The Project Attributes page displays a list of Core Attributes, if the user previously defined Core Attributes, and Project Attributes that the user has created to use with a Project.  New Project Attributes can be created on the page as well.

...

Primary Key -  For each Project a Primary Key needs to be defined to uniquely identify a record. This could correspond to a unique identification number of a customer, a device, or a combination of both. Primary Keys(s)  can be a single Attribute or a combination of Attributes. The Primary Key(s) will describe how your data is organized so careful consideration should be given when defining a Primary Key or Keys. The Primary Key Attribute(s) can be Project specific, or come from the list of Core Attributes.  Once created, the Primary Key for a Project cannot be changed. 

Project Segments

The Project Segments page displays a list of Segments if the user has previously defined Segments.  New Segments can be created on this page as well.

...

• Range - The user can create a range directive that will limit the Events to a particular range based on a count or time frame. A time frame Keep following a time frame Skip starts at the end of the Skip time period. A time frame Keep following an Event count Skip starts at the timestamp of the final Event skipped. Skip and Keep are both optional and the Starting From direction is required if there is a Skip or Keep.
  • Starting From - Drop down list, values are Oldest or Newest
  • Skip - A numeric field and drop down list to exclude Events
    
    • Numeric Field - The number of Events or extent of time frame
    • Drop Down List - Values are Events, Minutes, Hours, Days, Weeks
  • Keep - A numeric field and drop down list to include Events, after any skipping of Events
    
    • Numeric Field - The number of Events or extent of time frame
    • Drop Down List - Values are Events, Minutes, Hours, Days, Weeks
  • Note on millisecond accuracy: Time ranges include the millisecond of the event.  For example, lets assume the direction is Newest, Skip is 1 hour, Keep is 1 hour, and the event that triggered this rule occurred at exactly 3:30am.  In this case, an event at one millisecond after 2:30am will be skipped, and all events from 2:30am to one millisecond before 1:30am will be kept.
• Filters - The user can create as many Event and/or Attribute Filters as needed to apply to a Rule. The user does not have to create an Event Filter or Attribute Filter if they are no needed to create a triggering Segment.   
  • Event Filter - Evaluate incoming data based on events or time frame. For example, Newest 5 Events, Newest 2 Weeks, Newest 5 Minutes, etc.  If the user chooses the 'Oldest' reduction value the Unit option is limited to 'Events'.  This is to create a reliable static point in time for which to evaluate rules efficiently.
    • Reduction - Drop down list, values are Oldest or Newest
    • Value - Numeric value
    • Unit - Drop down list, Values are Events, Minutes, Hours, Days, Weeks
      
      • Click '+Add Event Filter' button to create an Event Filter that is displayed in the Filter list.  The user can create 1 or more Event Filters as needed.
  • Attribute Filter - Evaluate incoming data based on an Attribute value. For example, 'Country' field  'is'  value = United Sates, 'Opt-In' field 'is not' values = 'Undefined', 'Profile Updated' field 'is greater than' value = '2016-01-01', etc.
  • Attribute - Drop down list consisting of previously defined Project Attributes
  • Operator - This field will appear after an Attribute has been selected. This field is a drop down list with options based on the type of attribute chosen. 
    • For Text Attributes the available operators are -  is / is not / starts with / does not start with / ends with / does not end with / contains / does not contain / has any value / has no value
    • For Integer Attributes the available operators are -  is / is not / less than / greater than / has any value / has no value
    • For Float Attributes the available operators are -  less than / greater than / has any value / has no value
    • For Date Attributes the available operators are -  is / is not / is before / is after / has any value / has no value 
    • For Boolean Attributes the available operators are -  is true / is false / has any value / has no value
  • Value - This field is a fill-in field where the appropriate value will be defined.  This field is not available for a boolean attribute.
    • • Click '+Add Attribute Filter' button to create an Attribute Filter that is displayed in the Filter list.  The user can create 1 or more Attribute Filters as needed.
• Conditions - Evaluate incoming data based on an Attribute metric. For example, 'Newest' 'Opt-In' field  'is'  value = Yes, 'Average'  'Daily Temperature' field 'is less than' values = '80 degrees', etc.
  • Trigger if any events exist -  If clicked the Conditions section disappears. By selecting this option the campaign criteria will be based on the Audience that was defined for this campaign in the previous tab and the Event and Attribute Filters.
  • Attribute - Drop down list consisting of previously defined Project Attributes - The user must choose an Attribute in order to select a Reduction value.
  • Reduction - Drop down list of options based on the type of Attribute chosen.
    • For Text Attributes the available reduction values are -  oldest / newest / count 
    • For Integer Attributes the available operators are -  oldest / newest / count / average / sum 
    • For Float Attributes the available operators are -  oldest / newest / count / average / sum
    • For Date Attributes the available operators are -  oldest / newest / count 
    • For Boolean Attributes the available operators are -  oldest / newest / count 
  • Reduction explanation:
    
    • Count: This takes the number of times the specific attribute selected has been in an event for the filtered set of events. This includes the triggering event.
    • Oldest: The first event in the filtered set of events
    • Newest: The most recent event in the filtered set of events. This may not be the triggering event if an event had been sent in before the triggering event has been processed.
    • Average: For integers and floats only. This takes the average of all events that have the attribute value present. Events that are missing this attribute do not contribute to the average calculation
    • Sum: For integers and floats only. This sums all values of the events that have this attribute value present.
  • Operator - This field is a drop down list with options based on the type of Attribute chosen. 
    • For Text attributes the available operators are -  is / is not / starts with / does not start with / ends with / does not end with / contains / does not contain / has any value / has no value 
    • For Integer attributes the available operators are -  is / is not / less than / greater than / has any value / has no value
    • For Float attributes the available operators are -  less than / greater than / has any value / has no value
    • For Date attributes the available operators are -  is / is not / is after / is before / is in (last / next / today) /  is not in (last / next / today) / has any value / has no value 
    • For Boolean attributes the available operators are -  is true / is false / has any value / has no value
  • Value - This field is a fill-in field where the appropriate value will be defined.  This field is not available for a boolean attribute.

Export

• Event Data  - Incoming events
  • All historical - Selecting this radio button will export all of the event data associated with a particular Project. The approximate record count will display the total record count.
  • Date Range - The user can select a specific start date and end date. The approximate record count will update and display the total record count.
  • Authorization Checkbox - Users must authorize billing charges for exported data.
  • Data is exported and downloaded as a .csv file.

  • Export Data Header - Includes all Project Attributes that have been created.

    Timestamp

    Nanosecond

    Event ID

    Event Name

    Project ID

    CIID

    Offset

    Tags

    Project Attribute

    Project Attribute

    Project Attribute

    etc.

    
    

• Sent Messages Data - Campaign messages sent
  • All historical - Selecting this radio button will export all of the sent messages data associated with a particular Project. The approximate record count will display the total record count.
  • Date Range - The user can select a specific start date and end date. The approximate record count will update and display the total record count.
  • Authorization Checkbox - Users must authorize billing charges for exported data.
  • Data is exported and downloaded as a .csv file.

  • Export Data Header 

    CIID

    Campaign ID

    Message ID

    Creation Date

    Last Attempt

    APNS Count

    GCM Count

    Websocket Acknowledgement Count

    Websocket Send Count

    Read Count

    Status

    Message

    
    

Account

• Usage

This page maintains the event data and associated billing charges that occurred for an account during a month.  Historical usage and billing data is available and can be accessed by clicking on the drop down list in the upper right corner. 

• • Events Received - A total of all incoming events processed for all Projects associated with a user account.
  • Messages Sent - A total of all Campaign Messages sent for all Projects associated with a user account.
  • Records Exported - A total of all records exported for all Projects associated with a user account.

• Payments

This page maintains payment methods used for a user account.  The user can add, delete or edit credit or debit card information, and set the default payment method.

• Account Settings

This page is available to update account information

...