Banner_logo_board

Help - User's Guide

Table of Contents

Home

This is the main TapIn home page that describes the Tap In service.

A TAP is a TapIn Action Plan. This is a user-created automation process that will do work for the user.

A Thing is a category of services or devices that are accessible over the Internet.
TAPs connect to various Things to accomplish a task. TAPs can be executed on demand or on a user-defined schedule.

To try a TAP, go to the Try It section of the page. Clicking on the image, then hit the Play button. You can browse more TAPs by going to the TAP Store page and selecting Things, which represent types of services or devices TAPs can connect with, or tags, which are assigned to individual TAPs.

TAP Store

This page lists all TAPs that are shared with all TAP users. You can try a TAP by clicking on the image, then hitting the Play button.

You can execute a TAP under your account by first copying it. You can then view the TAP details, edit it, or have it run under a schedule.

The icons for a TAP show the Things that TAP uses. You must register for all the required topics in order to use that TAP. To register, go to the My Account, My Things page and add it. In some cases, authorization with the partner application is required.

You can also view TAPs grouped by the Things that they use, or by Tags that are assigned to a TAP by users.

My TAPs

List

All TAPs owned by your account are listed here. Click on the TAP image to execute or modify the TAP.

TAPs that are marked as “Favorites” are shown at the top of the page.

The icons for a TAP show the Things that TAP uses. You must register for all the required topics in order to use that TAP. To register, go to the My Account, Things page and add it. In some cases, authorization with the partner application is required.

Show

This view shows the detail of a TAP. From this page you can:

  • See the status of the plan, including

    • Whether the TAP is running. The icon on the top right corner indicates whether the TAP is currently running (icon) or stopped (icon).
    • What is the current state of the TAP process. The process graph shows the flow of tasks for that TAP. A blue marker shows which task is currently executing. The marker will move as tasks complete executing.
    • What Things this TAP uses.
    • Whether an input dialog box is shown when the TAP is executed (icon).
    • Whether an output dialog box is shown when the TAP completes (icon).
    • If the TAP is marked as public (shared on the TAP Store page) (icon).
    • Whether the TAP has a scheduled defined for it (icon), and if that schedule is enabled.
    • If geo-location is used (icon).
  • Execute the TAP (icon).

  • Administer the TAP details (icon).

  • Mark the TAP as a favorite (icon).

The icons for a TAP show the Things that TAP uses. You must register for all the required topics in order to use that TAP. To register, go to the My Account, Things page and add it. In some cases, authorization with the partner application is required.

When you execute a TAP by hitting the Play button, that TAP is submitted for execution in the Tap In service’s cloud. As the TAP executes, its results are shown in the output area below the TAP. The output text can be controlled by the user by editing the TAP process.

If an optional input dialog is defined for this TAP, the user will be prompted for information that is used by the TAP. For example, if the TAP is searching for new items, a dialog box can ask for search criteria.

Similarly, an output dialog can be defined for a TAP. This allows the results of a TAP to be easily shown to a user. For example, if the TAP is showing locations points, a map can be shown with markers on the location points.

Admin

The Admin page allows you to edit the TAP with the following options:

  • Display options

  • Copy

  • Delete

  • Edit Schedule

  • View Reports

  • Edit Process

  • Edit Tags

  • Edit Inputs

  • Edit Outputs

Display options

Hitting the edit button (icon) will open edit options for displaying the TAP card. The card’s name, description, background color, font color, icon and image can be set here. Note, the options on this page do not control how the TAP executes. They only control the look of the TAP card.

Copy

This button will allow you to create a copy of this TAP. The TAP logic and card display options are copied. However, the public setting and schedule are not copied. Once this button is selected, the display options for the new TAP are shown. Edit the options and hit the Create button to create the new TAP.

Delete

This button will delete the TAP and any defined schedules.

Edit Schedule

A schedule allows you to define when this TAP can automatically execute. You must define the following options

  • The criteria in each of these sections must be met in order to execute. Note that the time zone defined in the user’s My Account page is used for time and date settings.

  • Enabled/Disabled. A TAP must be enabled in order for the TAP to automatically execute. Use the disabled option to temporarily stop the scheduled execution.

  • Dates. Define the days that you want the TAP.

    • Every Day. There is no restriction on dates.
    • On one day. Select the specific day that you wish this TAP to execute.
    • Between dates. Select the start and end dates that you wish this TAP to execute. The start and end dates are included in the execution period. If the end date is not specified, the TAP will start executing on the start date, and will continue with no end date.
  • Days. Select the days of the week that you wish the TAP to execute.

  • Times. Once all the above criteria are met for a specific day, this section will determine what times of the day a TAP will execute.

    • Every Interval. Specify an interval between 5 and 60 minutes. The TAP will execute once every interval.
    • At specific times. Specify what times this TAP will execute on this day. You can select or enter a time to execute, using the format :(am|pm), for example 04:25pm or 12:15am. To add additional times, hit the plus icon to add an additional time field. To remove a time, hit the minus icon next to that time field.

When a schedule is defined for a plan, a clock icon will appear on the TAP card. If the schedule is disabled, the clock will be red.

Reports

Reports will show past TAP executions. Enter the date and the time range (optional), then hit the Refresh button.
There are two types of reports:

  • Summary History. This report will show the output of for each place executed in the TAP.
  • Detail History. This report will show each status change as the TAP executes, and the place name and class. The arrow icon (icon) indicates the start of a TAP.

Process Editor

Clicking to the Process Editor button will open the graphical interface that allows you to edit the execution logic of the TAP. The process editor allows you to define:

  • How the TAP will execute.
  • Which topics and methods are used.
  • The text sent to the output results section when the TAP executes.
  • The input parameters available for the inputs dialog box option.
  • The output parameters available for the outputs dialog box option.

The Process Editor is used to create a graphical model that determines what the TAP will do. The TAP consists of places, represented by circular icons, which are connected by arrows. Each place represents an action, for example sending an email or reading data from a source. A complete and valid TAP has a single start place (no input connectors) and a single end place (no output connectors). All places are connected. When a TAP executes, the start place executes. After it completes, the next connected place executes, and so on until the end place is reached.

The TAP graph is created by dragging and dropping places on the Process Editor’s drawing canvas, then dragging connector lines between the places. You can also create conditional execution by using constraints, which are connectors that enabled only if a condition is met.

You can also pass data from one place to another by using envelope keys, defined in the TAP properties. The envelope can be thought of as a data packet that flows to each place as it executes. The envelope can contain as many keys as required. A place can add data to or get data from a specified key in the envelope.

Once a TAP graph is completed, you can test the TAP by executing it, then checking the output console to see the status of each place as it executes. Once the TAP is working as expected, the user can save the plan, then return to the main page and execute the TAP from there.

The Process Editor main menu consists of the following buttons.

  • Home. This option allows you to Save the TAP or Exit the editor. The TAP is not saved to the TAP cloud service until the Save button is hit. The TAP is also automatically saved when the TAP is executed. This option also allows you to drag places to new positions on the canvas.

  • Properties. Clicking on this button will open a dialog box that will allow you to change the name, add comments, or add envelope keys. You can also define a default value for a key. This value is set at the beginning of the TAP. If inputs are defined for an envelope key, the entered input value will override this default value.

  • Add. This option will allow you to add the following graph components.

    • Places. This option shows the following place types. To add the place type, click and drag the place type icon onto the drawing canvas, then release. A dialog box where the place name and Tap In Integration Point, or TIP, can be defined. The TIP list shows the action that this place will execute. Once a TIP is selected, the options for that TIP will be shown.

      • Place (Standard). This is a normal place that executes the selected job, and then proceeds to the next single connection.
      • And Split. This place allows you to create parallel processing path. It MUST be paired with an And Join place. Each connection out of this place will launch a new job which will run in parallel with the main path. The envelope going into an And Split is copied and passed to each outgoing path.
      • And Join. This TAP merges the parallel paths created by an And Split place. All incoming paths must complete before the And Join place is executed. The data envelope of all incoming paths are merged, then passed to the outgoing path.
      • Wait. This place causes the TAP to stop processing until the selected job condition is met. When the condition is met, this job will restart at the place after the Wait place. For example, you can cause a TAP to stop for a period of time, the restart. The data envelope is maintained when the TAP restarts.
      • Supernode. You can have a TAP call the execution of another TAP. The called TAP works like a place in the parent TAP. This is implemented by the Supernode place, where you can select from a list of your TAPs.
    • Connector. To connect places, click on the button. The places now cannot be dragged. (To re-enable place dragging, hit the Home button). Click on the beginning place, then drag to the ending place, then release to create the connection.

    • Constraint. This option works like the Connector. When the connection is completed, a dialog box will appear where you can define a name and constraint condition. The constraint conditions are evaluated, and all must be true in order for execution to pass through this constraint. Each condition consists of:

      • Key. This select shows
        • The TAP envelope keys, as defined in the Properties. The format of the envelope key is “TAPIN{key_name}”.
        • The output keys of the incoming place. This allows you to determine execution path based on the last place’s results.
        • Operator.
        • ==, !=. This will match if the key value equals/not equals the value.
        • >, >=, <, <=. These arithmetic operators will interpret the key and value as numbers, and will match if the numbers the comparisons are true.
        • Has. This will match if the key value string contains (case insensitive, regular expression match) the value.
        • Value. Enter the value to match. You can specify an envelope key’s value here by using the text “TAPIN{key_name}”.
  • Edit. After a TAP is created, you can modify any place setting by clicking on this button, then clicking on a place. The place settings dialog box will show, allowing you to modify any place setting. You can not modify connectors or constraints; you must delete them first, then add them.

  • Delete. To delete a place, connector or constraint, click on this button. The end points of connectors will show in red.

    • To delete a place, click on the place. You will be prompted to confirm deletion.
    • To delete a connector, click on the red dot at either end of the connector.
    • To delete a constraint, click on the constraint symbol (bar icon). To modify a constraint connection, do not click on the constraint connectors. Rather delete the entire constraint then add a new one.
  • Test. This option allows you to confirm the operation of your TAP.

    • Execute. This button will start execution of the TAP. As each place executes, the blue token icon will move to the place that is executing. Completed places will show a grey token icon in the place. The TAP status and results of each place execution is shown in the table below the canvas. If you move your mouse over a place, only the messages for that place will show in the table (highlighted in yellow).
    • Kill. If a TAP is running, you can stop it by hitting the Kill button.
    • Validate. A TAP will only execute if the graph has a valid topology, which means:
      • A single start place; that is a place that has no inputs. This will be the first place that executes.
      • A single end place; that is a place that has no outputs. This will be the last place that executes.
      • All places are connected.
      • There is a path from the start place to the end place.
      • Each And Split place has a corresponding And Join place. Clicking on this button will check the validity of the plan, and return the result on the output console.
    • Clear. Clicking this button will clear the contents of the output table and clear the token indicators in the places. After this button is hit, new updates will update the graph and output table.

Edit Tags

Tags can be assigned to TAPs in order to aid in searching for TAPs with certain characteristics. Any word or words can be used as a tag. You can add as many tags as you want to a TAP. Tags assigned to a TAP appear in blue in the tag field. When entering a new word in the tag field, existing tags that match the entered word will appear and can be selected. After your tag words are typed, hit the Enter key to set the tag. To save the tags, hit the check icon.

To delete a tag, hit the x next to the blue tag.

The Community page contains a list of all defined tags. Click on a tag to see all public plans assigned to that tag.

Edit Inputs

Plan inputs allow you to pass data parameters to a TAP via in input form. For example, TAPs that require the user to enter a TAP option can define that option as an input field or a selection list.
In order for you to define an input, you must first have envelope keys defined in the Process Editor. Once there, the Admin page will let you assign a key to a form element. When the TAP execute button is hit, the form element will appear. After the user enters the data, it will be passed to the TAP for execution.

To add an input, click on the New button. A dialog box will appear. In the Name select box, select one from the envelope keys (defined in the Process Editor) for this TAP. Next, select the Input Type from the following form elements.

  • Checkbox. A checkbox form will pass the value to the TAP if checked.
  • Radio. NA
  • Select. NA
  • Text field. A text input field form will allow the user to enter data, which will be assigned to the input key.
  • Text area. A text area form will allow the user to enter a long data string, which will be assigned to the input key.
  • Map location. A Google map will allow the user to select a single location on the map. That coordinate (latitude/longitude) will be passed to the TAP.
  • Map area circle. A Google map will allow the user to select a circle area on the map. The circle center coordinates (latitude/longitude) and radius will be passed to the TAP.
  • Map area rectangle. A Google map will allow the user to select a square area on the map. The southeast and northwest coordinates (latitude/longitude) will be passed to the TAP.
  • Current location. This option does not create a form dialog. The current location of the user is automatically passed to the TAP. The HTML5 geo-location method is used so GPS-enabled mobile devices will pass accurate coordinates to the TAP. The browser’s geo-location feature must be enabled.

Additional options may appear, depending on the element selected. Complete the form to create the input.
To delete an input, click on the trash icon on the input line.

Edit Outputs

Outputs allow you to display the results of a TAP in a form element. Normally, TAP results are displayed like a console in the results area of the page. Use this feature to highlight output data or change the way the data is shown. After the TAP executes, if an output is defined, a dialog box will appear, and the defined outputs will be displayed.

To add an output, click on the New button. A dialog box will appear. In the Name select box, select one from the envelope keys (defined in the Process Editor) for this TAP. Next, select the output Type from the following form elements.

  • Text. The selected key value is shown in plain text.
  • Object JSON. If the selected key value is a data object rather than a string, the object will be displayed in JSON form.
  • Object pretty. If the selected key value is a data object rather than a string, the object will be formatted in a easily-readable form.
  • Map location. If the selected key is an array of coordinates (latitude/longitude), a Google map will be displayed showing the coordinates as map markers.

My Account

This page allows you to change your account settings, including:

  • Email. This used as the email address. For Email topic places, this field is used if an email address field is empty.
  • Name.
  • Public Alias. For TAPs marked public, this field is shown in the Author field.
  • Phone number. For SMS topic places, this field is used if the phone mail field is empty.
  • Time Zone. Time fields used in all forms use this time zone. This includes TAP output results, report criteria, scheduling forms and place form.
  • Password. Click on the My Password tab and complete the form to change the password.
  • Things. Click on the My Things tab to add or delete topics assigned to your account. Things represent your areas of interest. When you assign a topic to your account, you can then:
    • Execute public TAPs that use this topic. Check the TAP icons to list all the topics used by a TAP.
    • When using a plan’s Process Editor, that topic’s jobs (or actions that place can execute) will be listed.
      Things that are already assigned to you are listed in the My Things select list. From that list you can delete or edit an assigned topic. To add a topic, select an entry from the Select Things to Add list, then hit the Add button. Each topic’s registration process is different, depending if additional authorization is required with a Tap In partner. In those cases, you must authorize Tap In to access that account during topic registration. The authorization process and security guidelines defined by the partner are followed by Tap In.
  • Deactivate account. To close your account, click on this button. Your login ID will no longer be active.

TAP Development Process

  1. Figure out exactly what you want to do!
  2. Go to My TAPs and add a new TAP.
  3. Define a name and how you want your TAP card to look. Create it.
  4. At the admin TAP page, go to the Process Editor.
  5. Create the TAP process graph. a. Add envelope keys (via properties button) as required. b. Make sure you register with the topics you want to use, depending on your areas of interest. c. Test your TAP.
    d. Check that the automated actions are working as you expect.
  6. Save and exit to the TAP admin page.
  7. (Optional) If you want the user to enter data when it executes, add Inputs.
  8. (Optional) If you want to display data in a dialog or map, define Outputs.
  9. Test you TAP by executing it by going to the Show Plan page and hitting Play.
  10. (Optional) If you want the TAP to execute automatically, create a Schedule. From the TAP admin page, hit the Create Schedule button.
  11. (Optional) After the TAP is working as you expect, you can share it with other users by making it public. From the TAP admin page, hit the Make Public button. The TAP will appear on the Community Page, and other users can copy it to their account. IMPORTANT - make sure you remove any private information from the Process Editor’s place forms. Default information used when the place form fields are empty (ie, email, phone number) and your topic authorization information defined in your Account settings are not copied. However, data explicitly entered in place forms are copied.

Things

Dropbox

Dropbox cloud storage.

Dropcam

Control Dropcam video cameras.

Email

Send an email message.

Finance

Financial market data for stocks, exchanges and indexes.

Fitbit

Fitbit personal devices

GPS

TAP mobile GPS data processing

Hue

Control Philips Hue lights.

Network

Networking functions.

Parking

Find parking locations in my area.

SMS

Send and receive text messages.

Sentiment

Sentiment analysis tools for interpreting English text.

Tap

Tap In plan control functions.

Traffic

Get traffic information by location.

Twitter

Interact with Twitter. Send and read tweets from your Twitter account.

Weather

Get weather information by location.

Withings

Withing personal devices.

Yelp

Search Yelp for business reviews

Icons

Definitions


* Card
* Constraint
* Geo-location
* Graph or TAP graph
* Inputs
* Job
* JSON
* Object
* Outputs
* Partner (Tap In partner)
* Place
* Place Job
* Plan
* Process Editor
* Public
* Schedule
* Tag
* TAP
* Thing