TheNeedle

TheNeedle

TheNeedle Platform helps communities turn information into action with an intuitive and accessible crowdsourcing and mapping tool.
By enabling the rapid collection, management and analysis of crowdsourced information from NPS-OSINT and other sources, TheNeedle empowers everyone—individuals, community groups, governments, activists, organizations—to create meaningful change.

Managing People on your deployment

Roles

This feature allows you to set up and manage default and custom roles and permissions for different user groups on your deployment. Each deployment has a default “Admin” and "Member" role, which cannot be deleted, but can be edited. The default “Admin” role allows for full control over ALL functionality on your deployment, while the default "Member" role only grants access to edit their own posts.

Setup Guide

To access the roles management page,

• On the left hand menu bar, click on Settings

Settings button on the TheNeedle Platform sidebar

• Then, click on Roles

Settings list page. Roles button highlighted

• You’ll be redirected to a page with a list of all existing roles - default & custom roles (created by admins if any exist).

Add Role

To add a custom user role,

• Click on the yellow Add icon

Settings list page. Roles button highlighted

• Add the following details
  • Name: Provide a name for this new custom role
  • Description: Provide a brief description of what/who this custom role has been created for
  • Set your permissions. Below is a brief breakdown of what permissions get granted to users on selecting the options provided.
    • Manage Users: Allows for;
      • Viewing Users
      • Adding, Editing, Deleting Users
      • and Changing roles for Users
    • Manage Posts: Allows for;
      • Viewing posts
      • Editing and Deleting Posts
      • Publishing posts (Setting specific audiences to view )
      • Adding posts to collections
      • Creating new collections
    • Manage Settings: Allows for managing;
      • General Settings
      • Map Settings
      • Data Sources
      • Surveys
      • Categories
    • Bulk Data import and Export: Allows for upload of data via CSV files and exporting files.
    • Edit their own posts: Allows for editing of posts submitted by user
    • Manage collections and saved searches: Allows for
      • Addition posts to all saved searches/collections on
      • Removing posts from all saved searches/collections
      • Editing all saved searches/collections
      • Deleting all saved searches/collections
  • Click on Save.

The add role page contains a role name, description, and preferred permissions.

Edit Role

To edit a role

• Click on a role from the list provided to you.

Click on a role from the Role.

• On redirection to the edit page, make your desired changes to the role (i.e fill out details as directed in the Add role section)
• Click on Save to update the role.

Adding details to a new role. Name, description and permission fields available.

Delete Role

• To delete a role
• Click on a role from the Roles management list page

Selecting a role in the roles list.

• Then, click on the Delete This Role button at the bottom of the page

Click the DELETE THIS ROLE button.

• A pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete the custom role. If
  • You would like to proceed with deletion, click on Delete
  • You would not like to proceed with deletion, click on Cancel

Delete role confirmation pop up.

Users

Setup guide

To access the User management page,

• On the left hand menu bar, click on Settings

Settings button on the TheNeedle Platform sidebar

• Then, click on Users.

Settings -> Users

• You’ll be redirected to a page with a list of all existing users on your deployment
• From here, you can search for users either by name or by custom role

Adding new users

To add a new user,

• Click on the yellow icon as shown below

• Fill out the details below
  • Display Name: This is the name that will be displayed
  • Email address: This is the email address that will be tied to this new user’s account, and will be used to log in.
  • Password: Set a strong and secure password for your new user. Each password must have at least 7 characters
  • Role: Choose the level of administration access you would like this user to have
• Click on Save to create one.

Editing users

To edit a user,

• Click on the user you intend to edit from the user list page

• You should be able to edit the user’s display name, email address, password and user role from this page.

• Click on Save when done.

Changing User roles

You can change multiple users’ roles at once from the user management page.

• Tick the checkbox on the left, adjacent to the user(s) whose role you would like to change from the user list page
• This action will activate the previously inactive Change Role dropdown button on the top menu bar.

• Click on this dropdown and select the role you would like to assign your users to.

• A pop up box will appear, prompting you to confirm whether you would like to change the roles of your user(s)
  • Click on OK to change your user(s) role
  • If you’d like to cancel the role change process, click on Cancel.

Deleting users

Similarly, you can delete multiple users at once from the user management page, or from the individual user edit page.
To delete a user

• From the individual user edit page
  • Click on the user you intend to edit from the user list page.

• • Click on Delete User.

• • A pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete your user
    • Click on Delete to delete your user
    • If you’d like to cancel the user deletion process, click on Cancel.

• • From the User management page
    • Tick the checkbox on the left, adjacent to the user(s) you would like to delete from the user list page
    • This action will activate the previously inactive Delete button on the top menu bar. Click on it to initiate the deletion process.

• • • A pop up box will appear, prompting you to confirm whether you would like to delete your user(s)
      • Click on Delete to delete your user(s)
      • If you’d like to cancel the user deletion process, click on Cancel.

Modes for visualizing and managing data on your deployment

TheNeedle platform provides you with modes to not only visualise your data in different ways, but to also manage it.
We designed “modes” for the discrete and specific actions users need to take within the platform, in a bid to make the platform to be more intuitive and action-oriented for different user types on a deployment. Ordinary viewers of deployment can access three different modes as shown below:-

• Map view
• Data view
• Activity view
• Then, click on Users.

Logged out version of the sidebar of an TheNeedle deployment.

Signed in users(with the necessary permissions) can access four different modes as shown below:-

• Map view
• Data view
• Activity view
• Settings page

Logged in version of the sidebar of an TheNeedle deployment.

Your TheNeedle deployment defaults to the map mode for anyone who visits your homepage(as illustrated above). To change your current mode, select any of the options provided to you from the menu on your left.

Map View

This mode displays all published posts on a map.

• Each post appears as an icon on the map. In the event that you opted to combine nearby posts on your Map settings page, posts adjacent to each other on the map will cluster together, displaying a number denoting number of posts combined.
• Clicking on each individual post displays a small pop up box with the post title and description.
• You should also be able to zoom in and out of the map as desired.

Example of the Uchaguzi deployment with the map view.

You also get a breakdown of incoming posts by source, as shown below.

The map view sidebar allows you to filter out Data sources.

Data View

The Data view allows you to view, triage, and manage posts coming into your deployment as a chronological list of events over time. It provides a split pane that lists post summaries on the left pane, and post details and editing features in the right.

A list of posts on the left side of the data view. Click on one to select it.

From here, you should be able to:

• Add new posts

Adding new posts via the yellow + circle button.

• View individual post details
• Edit posts to either change existing structures or assign posts from Twitter, SMS and/or email to a survey

• You can also
  • Add posts to collections
  • Publish posts
  • Put posts under review
  • Archive posts
  • Share posts
  • Delete posts

Click on the "..." button on a post to see a list of actions.

Listed actions: edit, add to collection, share, publish, put under review, archive, delete.

• Get notified when new posts arrive

Click on the "..." button on a post to see a list of actions.

• Perform bulk actions( publishing, putting under review, archiving, adding to collections and deleting) on multiple posts at a time

Highlighted: bulk actions button.

Highlighted: bulk actions. Publish, Put under review, Archive.

NB: Data displayed on this page is dependent on permissions granted to the user viewing this page

Activity View

This mode gives you a summary of how people are interacting with your deployment over time.

Highlighted: select time frame button.

Highlighted: time filters.

You can compare

• Activity over time

Activity over time. Select "Compare" dropdown to get different types of activity data.

You can filter post count in a line chart over time by:-

• All posts
• Categories that the posts belong to
• Surveys that the posts were submitted to
• Status i.e whether they’re published or not

Highlighted: compare options. All posts, categories, surveys, statuses.

You can opt to view your post counts on the graph as cumulative totals.

• Activity by Volume

Highlighted: comparison type dropdown. "Categories" option selected.

• You can filter post count in a bar chart by volume by:-
  • Categories that the posts belong to
  • Surveys that the posts were submitted to
  • Status i.e whether they’re published or not

Highlighted: comparison type dropdown. "Categories" option selected. Other options: survey and status.

Managing Data in your deployment

A post is a report of a single instance of something in the deployment. It can be made up of many fields, such as Title, Description, Date, Links, and/or location. TheNeedle allows for collection of posts via

• Web (NPS-OSINT): You can setup a feed from nps-osint.co.za based on specific keywords, search terms, and/or artificial intelligence message classifiers.

This chapter will describe how to manage data coming in from these different sources.

Setup Guides

Viewing Posts

Posts on your deployment can be categorised into two types of data:-

• Structured: Incoming posts from the web platform and smartphone applications are classified as structured posts, since they adhere to the structure of surveys created on your deployment.
• Unstructured/Unknown: Incoming messages from SMS, Twitter and Email are classified as unknown posts, since they do not adhere to the structure of surveys created on your deployment. This means that these messages come in their raw form, and have to be manually structured by admins/anyone with permissions to edit posts, to fit into the structure of your survey. E.g an SMS message “Hello, my name is Angela” will need to be broken down into a title, a description, properly categorised etc.

You can view posts in either Map, Data or Activity mode. We'd previously discussed each of these modes separately in Chapter 5.

For purposes of managing your data, we recommend using Data Mode. From this page, You should be able to see the following:-

• A list of all posts in chronological order of when they were submitted into the platform. You can opt to change the order of the posts either through options provided in the search filter ( we'll dive into filtering posts in the next section )
• Post visibility Status: You can tell if a post is public or only visible to a specific audience
• Post source (is it from the NPS-OSINT or another source?).

• Structured posts via web/smartphones will have their respective source label on them.
• Unstructured posts will have a label denoting their source, as seen below with this sample NPS-OSINT message

• When the post was submitted: Hovering over the timestamp of the post will give additional details on specific timing as shown below.

• Individual Post descriptions on the left pane, and post details on selection of a post card on the right pane

• When viewing post details on the right pane, you'll be able to see additional details such as location, categories, and tasks.

• If you’re an admin/your user role permits, you’ll should also be able to see the Edit button on the top right-hand corner of your page

NB: Locked posts - The platform allows for post locking, to avoid duplication of efforts. If someone on your team is currently editing a post, it is locked and made unavailable for you to edit. In this case, the edit button will not be visible to you, despite having adequate permissions.

• Every post has a three-dotted icon as shown below. Depending on what permissions are granted to the person viewing, this button allows you to
  • Add your post to a collection (public)
  • Share this post (public) via facebook, twitter, embed on another website or export it to a CSV file.
  • Edit your post (limited by role)
  • Publish your post (limited by role)
  • Put your post under review, setting visibility to only members of your team (limited by role)
  • Archive your post (limited by role)
  • Delete your post (limited by role)

• A search filter that allows you to
  • sort posts by
    • Date of creation
    • Post date i.e date when it was assigned to a survey
    • Date updated
  • filter reports by Saved searches, Status, Surveys, Categories, Data source, Date range, Location or any other user determined parameters.

Please note that information displayed to users on each of these pages is dependent on permissions granted to registered/non registered users by the deployment administrator e.g Published posts, Unknown posts and My posts, and menu bars allowing for editing and deletion are only visible to logged in users with necessary granted permissions.

Filtering Posts

Filters can be applied to narrow down a large amount of data. You can filter posts by many types of parameters, for example: Surveys, Categories, Status, Date Ranges, and Location.
Survey and Category filters are located within the "Filters" modal on the top global search bar, which allows you to

• sort posts by
  • Date of creation
  • Post date i.e date when it was assigned to a survey
  • Date updated
• filter reports by
  • Saved searches
    • By default, every deployment has a set of three featured Saved Searches(read more in the Saved Searches section of this manual) from which you can view posts on your deployment, from the search filter.These include:-
      • Published Posts: Lists all posts that have been made public on your deployment(i.e can be viewed by registered/non-registered users on your deployment.
      • Unknown Posts: Lists all messages received from SMS, Email and Twitter, that have not been assigned to a survey i.e are unstructured
      • My posts: Lists all posts created by you as a user
  • Status
    • Published: Posts that can be seen by both logged in and non logged in users
    • Under review: Posts that can only be seen by logged in users with adequate permissions
    • Archived: Posts that have been deemed to be irrelevant and removed from your active view
  • Other filters include Surveys, Categories, Data source, Date range, Location or any other user determined parameters

Filters are additive, so you can apply as many as you would like. This search filter is available on all pages.

Adding Posts

Directly from the NPS-OSINT Registered users can create posts using the same process described below. For descriptive purposes, the post below has one tasks. To create a post,

• Click on the yellow add icon as shown below on your homepage, or on the bottom left corner on the data mode page

• In the event that you have multiple surveys on your deployment, you’ll have to choose the survey from a list of all surveys available on your deployment.

• At the upper left corner of the page, click on the dropdown menu and see the available languages that the survey form can be viewed in, click on the language you prefer and fill the form in the chosen language.
• Make sure to fill out all fields with a red asterisk beside them, You will not be able to save or publish your post before these fields are filled out.
  • NB: Users are now able to submit improvements to the OpenStreetMap Basemap, directly from the post submission page. In some cases, base maps are not up to date. We highly encourage you to contribute to improving base maps in your locations of interest. For more details on how to improve OpenStreetMap, visit the OSM wiki here.
• Make sure to fill out any tasks visible to you on this submission page as well. NB: You can submit posts without filling out or completing tasks. However, in the event that your task is a requirement for publishing, this post will not be published unless the task is marked as complete.
• When you’re done adding content for your post, click on Submit.

• Your post will be submitted to the deployment’s admin for review before publishing.

Editing Posts

The post editing function is only available to admins or registered users with adequate permissions. This means that non registered users cannot edit posts.
This feature is particularly useful when creating posts out of unstructured posts (messages from SMS, Email, Twitter).
To edit a post,

• Select a post from your data view

• Click on Edit. This will load the post editor on the right pane of your page, where you’ll be able to edit any of the content.

• If you're logged in and have adequate permissions you should also be able to change the status of your post.

• When done making changes, click on Save.

Locked posts

Data processing and analysis should be collaborative. When you start editing a Post, it will be locked and other users cannot edit, update, or accidentally interfere with your work. When you finish working and save or close the post, it is automatically unlocked again. Conversely, if you need to edit a Post that is currently locked you will be able to quickly find out which of your colleagues is working on it and coordinate changes with them.
To avoid issues with Posts remaining locked, we have introduced a set of safeguards to ensure that the Posts will always return to an unlocked state.

• Locks expire after 5 minutes, to avoid locking a post when someone is not actively working on it.
• When a user logs out, all of their locked posts will be unlocked.
• Administrators have the right to “break” a lock to ensure that a Post becomes available again in a time sensitive situation.
• Even when locked for edit, all users who have permission are able to view and review the Post.

Publising Posts

The ability to publish posts is only available to admins or registered users with adequate permissions. This means that non registered users cannot publish posts. Posts submitted by non registered users have to be moderated.
To publish a post, simply change the status to Published as shown below:

• From the data view page, either
  • Individually or

• • in Bulk

• From the post detail view

• While editing a post

• Then, click on Save.

Deleting Posts

The ability to delete posts is only available to admins or registered users with adequate permissions. This means that non registered users cannot delete posts.
You can select multiple posts to delete at a time from the post list page, or delete individual posts from the list page, or individual post view page. To delete

• An individual post from the data view, click on the three dotted icon from the list of detail pane as shown below, then click on Delete

• A pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete your post
  • Click on Delete to delete your post
  • If you’d like to cancel the post deletion process, click on Cancel

• Multiple posts from the post lists page
  • Click on bulk actions, then tick the checkbox on the left, adjacent to the post(s) you would like to delete from the posts list page. You can also click on Select All to grab all posts listed on that page.

• • This action will activate the previously inactive Delete button on the grey menu bar.
  • Click on it to initiate the deletion process

• A black pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete your post(s)
  • Click on Delete to delete your post(s)
  • If you’d like to cancel the post deletion process, click on Cancel

Analysing Data on your deployment

Saved Searches

Saved searches are dynamic groupings of posts that match parameters chosen in filters.They are dynamic because as new posts are added that fit the search criteria, they will show in the saved search automatically, and without manual intervention.
Saved searches are particularly useful for managing workflows and teams on your deployment. They allow you to set filters for information that’s relevant to each working group/team. For example:

• It is useful for a team tasked with structuring to only see posts that are unstructured. Creating a saved search with these parameters will be useful
• A team tasked with publishing needs to only see posts that are yet to be published, so creating a saved search with these parameters will be useful.

Please note that only registered users can create Saved searches. Non registered users can only view public searches

Creating a saved search

You can create a saved search from your homepage by:

• Adding your search/filter parameters on the search bar as shown below.
  • A Save Search button will appear on the search and filter modal.

• • Click on it.
• A small pop up box will appear, asking you to fill in the following details:

• • Assign a saved search name
  • Provide a description
  • Set the audience allowed to see this saved search
  • Set the default viewing mode for this saved search(choosing between Map, Data or Activity). This is the view that a user will see when they first arrive at this saved search
  • Determine if this saved search is featured or not. Setting this saved search as featured displays to all users on the saved search menu
• Click on Save&Close when done.
• Your saved search should now appear on the Saved Searches menu bar on your search bar.

Updating a saved search

You can update a saved search at any time by adding/editing your filters/keywords, or turning off existing filters/keywords.

• Set your parameters on the search bar by either typing or selecting options from the search
• An Update Search button will appear on the menu bar on the left of your screen. Click on it.

Adding a notification to a saved search

Not Implemented

Editing a saved search

To edit a saved search,

• Select saved search you would like to edit from the search filter.

• Click on Edit as shown below:

• Edit your saved search details, then click on Save&Close.

Deleting a saved search

To delete a saved search,

• Select saved search you would like to delete
• Click on the three dots button, right next to the Edit button.

• Click on Delete. A pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete your saved search.

• Click on OK to delete your saved search
• If you’d like to cancel the saved search deletion process, click on Cancel

Collections

A “Collection” is a manually-curated grouping of posts. It is not dynamic, meaning the posts within it do not change unless a you manually update them.
You may find collections useful in grouping posts that you would like to share with external partners . For example , you may find it useful to add allposts that require escalation to a collection and then export data in that collection in a CSV file that youcan share with partners.
Please note that only registered users can create Collections. Non registered users can only view featured public collections

Creating new collections

To create a new collection,

• Click on by clicking on:
  • Collections icon on the bottom left hand corner of your deployment as illustrated below.

• • The three dotted icon on the data view page while viewing the list on the left and the detailed pane on the right. ( note that this will assign this post to the new collection created.

• • A pop up box will appear, with a list of all existing collections, and a Create new button. Click on it.

• • Then, fill in the following details:

• • • Assign a Collection name
    • Provide a description
    • Set the audience allowed to see this collection
    • Set the default viewing mode for this collection (choosing between Map, Activity, or Data). This is the view that a user will see when they first arrive at this collection
    • Determine if this collection is featured or not. Setting this collection as featured displays to all users on the collections menu
  • Click on Save&Close when done.
  • Your collection should now appear on the left menu bar under Collections

Adding Posts to collections

You can add a post to a collection from:

• The three dotted icon on the data view page while viewing the list on the left and the detailed pane on the right.

• A pop up box will appear, with a list of all existing collections. Select the collection(s) you’d like to add the post to.

• You can add a post to multiple collections, so tick all checkboxes that apply.
• You can also create a new collection to add the post to from these two pages. Simply click on Create New from within this dropdown as described in the Creating new collections.

Adding notifications to collections

Not Implemented

Adding notifications to collections

As a registered and logged in user, you can set up notifications on Collections. This means that any time a post is added to a collection, you will receive an email or phone notification. To add a notification,

• Click on the collection you’d like to receive notifications from.
• Click on the three dots button, right next to the Edit button.

• Click on Get Notifications.

• You can turn off notifications for this collection using the same process described above.

Editing Collections

To edit a Collection,

• Click on the collection you would like to edit
• Click on Edit as shown below:

• Edit your Collection details, then click on Save&Close.

Deleting Collections

To delete a collection,

• Click on the collection you would like to delete
• Click on the three dots button, right next to the Edit button.

• Click on Delete. A pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete your collection.

• Click on OK to delete your collection
• If you’d like to cancel the collection deletion process, click on Cancel

Credits

This platform is based on the Ushahidi platform please see their website at http://www.ushahidi.com/