What does Ushahidi Do?

• Ushahidi is a tool for collecting, managing, and visualizing data.

• Data can be collected from anyone, anytime, anywhere by SMS, email, web reports, mobile applications, and twitter.

• Posts can be managed and triaged with filters and workflows.

• Data can be managed and visualized in different ways : on a map, as a list, or in different charts and tables through the activity view.

Who is Ushahidi For?

While anyone can use Ushahidi, traditionally it has been a tool used by Crisis Responders, Human Rights Reporters, and Citizens & Governments (such as election monitoring or corruption reporters). We also serve environmental mappers, asset monitoring, citizen journalism, international development, and many others.

What's New in Mzima Platform?

The functionalities of the mzima platform remain largely the same with what was in v3 platform.

• Client: The main difference is the improved user interface and user experience.

• Backend API:

  • Transitioned to a newer version of the Laravel framework: For enhanced performance, scalability, and productivity. With Improved documentation.

  • REST API v5 Completion which empowers you to extend the capabilities of the Ushahidi Platform effortlessly.

  • Deprecation of REST API v3 Implementation

Note: Work is still ongoing to incorporate functionalities from previous versions into mzima platform, and also add enhanced and new features.

You must have fulfilled the prerequisites below to translate the Ushahidi User Manual into your preferred language.

Prerequisites

• Download the User Manual as PDF: To download the User Manual as PDF to your local machine, kindly follow the guidelines outlined in Downloading the User Manual section.

• Have a stable internet connection (for online translation tools).

The setup for different methods in this guide is demonstrated in the videos below. You can watch and follow the guide at the same time!

Method 1: Using Google Docs

Google Docs allows you to translate PDFs seamlessly into any language. Follow the steps below to translate the Ushahidi User Manual into your preferred language.

Video setup guide

Setup guide

Uploading the PDF to Google Drive

• Go to Google Drive.

• Click on the + New button on the top left side of the page.

• Select File upload.

• Choose the PDF file you want to translate and click the Open button to upload it to Google Drive.

Opening the PDF with Google Docs

• Select Open with > Google Docs. This will open the PDF file as a Google Docs document.

Translating the document

• Wait for the document to open in Google Docs and then go to the Tools menu at the top left of the page.

• Select Translate document. This will display a pop-up requiring you to name the translated document and choose a language.

• You can rename the default title or leave it that way. Click the drop-down icon to select your preferred language.

• Click the Translate button and wait for it to translate the document. The translated document will open in a new tab.

Downloading the Translated Document

• Preview the translated document.

• Go to the File menu at the top left to download the translated document as a PDF.

• Click Download > PDF Document (.pdf) to download it to your local machine.

Method 2: Using Google Translate

Google Translate provides an easy way to translate PDF documents directly through their website. To use Google Translate to translate the User Manual into your preferred language, it is advisable to download a section of the manual, as most free online PDF translator tools require an upload size not larger than 10 MB. Visit the Downloading the User Manual section for a guide on downloading a section of the User Manual.

Video Setup

Setup guide

• Open your browser and go to Google Translate.

• Click on the Documents tab at the top left corner of the page.

• Click the Browse your files button to upload your PDF document or drag and drop it.

• Select the PDF file you want to translate and click the Open button.

• Once the document has been uploaded, click the drop-down icon to select your preferred language.

• Select your preferred language and click the Translate button.

• Click on Open translation to preview the translation or click the Download translation button to download the translated PDF to your local machine.

Method 3: Using Immersive Translate

The Immersive Translate extension offers a free PDF translation feature that enables users to translate PDF documents into various languages while preserving the original layout. It allows users to download either a translated-only version or a bilingual version of the PDF, which displays the original and translated texts side by side.

To learn how to translate the Ushahidi User Manual into your preferred language using Immersive Translate, visit the Immersive Translate website.

Ushahidi is a non-profit technology company working to change the way information flows in the world. Founded in Nairobi, Kenya during the 2008 election violence and human rights abuses, Ushahidi means "testimony" in Swahili.

We build digital tools and run programs to give marginalized people a voice. Since 2008, the Ushahidi Platform has grown to be the world-class open-source tool for human rights activism, crisis response, and transparency.

Global Mission

The Ushahidi Platform has been deployed more than 100,000 times in more than 159 countries, in 45 local languages, with 7 million testimonies, reaching nearly 20 million people. The platform has become a replicable solution for people worldwide, from Syrians reporting on human rights abuses at Syriatracker.crowdmap.com to tracking human rights abuses in Nepal at Nepalmonitor.org.

People around the world need a way to share their voice during a critical situation, to ask for and generate support, and to bring transparency to their issues. At the same time, organizations and governments lack understanding of what is happening on the ground; they need a way to make sense of how to respond effectively and quickly. These are just a handful of the thousands of impactful uses of the Ushahidi platform to amplify people’s voices.

To learn more about Ushahidi's impact, please check the Impact Report.

Innovation is born here, ecosystems created.

Ushahidi has built six open-source software products: the Ushahidi Platform, SMSsync, Crowdmap, SwiftRiver, CrisisNet, and TenFour. Ushahidi has run numerous large on-the-ground programs that utilize its software and expertise, including the Haiti earthquake response, the Uchaguzi election program, the Resilience Network Initiative, and Making All Voices Count - a grand challenge for development.

In addition, Ushahidi has successfully catalyzed six organizations that work across its collective vision to create technologies that provide access, change the way information flows in the world, and improve decision-making. Together these organizations form the Ushahidi Ecosystem, an association, that works together to focus on how technology can and should be used for doing good in the world to solve global problems like humanitarian response & democracy (Ushahidi), technology-enabled humanitarian volunteering (Standby Task Force), open data as a global resource (Popily), making things to create jobs and economic growth (Gearbox), women in tech, job creation and empowerment (AkiraChix), technology built by and for the developing world (iHub), and access to information (BRCK).

At the top left of this overview page, and any page of the Ushahidi platform User Manual, you will find a dropdown element where you can get to select the version of Ushahidi platform User Manual that you want to view. If you are on a mobile phone, then this dropdown is somewhere in the sidebar.

This guide has been updated based on content created on the initial support documentation by Sophie Shepherd, and new content on previously undocumented features by members of the Ushahidi team.

This manual gives you a step by step overview of how to set up an Ushahidi [Mzima] deployment, and how to make full use of the features the platform offers.

This manual will show you how to install the Ushahidi platform, sign up for an ushahidi account, customise it to meet the needs of your project, manage people and incoming data, as well as visualise and analyse your data. It is meant to be a comprehensive learning guide for brand new users of the platform, as well as a reference point for those who may have some prior experience using the platform.

If you need some guidance or have questions, reach out to us via:

• Our chat feature on http://ushahidi.com

• Live Developer chat rooms on Gitter/Skype/IRC (posting on any one of these channels will post on all of them simultaneously)

Bumped into a bug on the platform or have a feature you would like to request? Share your feedback with us via our github issues page.

Looking to contribute to the Ushahidi platform? Visit our contribution guide for directions on how to get started.

Feedback is welcome and will be incorporated into the guide.

To access the Ushahidi documentation offline, download it as PDF to your local device.

The setup in this guide is demonstrated in the videos below as well. You can watch and follow the guide at the same time!

Prerequisites

• Stable Internet Connection: Ensure you have a reliable internet connection to avoid interruptions during the download.

• Free Space of 40MB: Ensure your device has at least 40MB of free space to accommodate the PDF file.

• PDF Reader Installed: You should have a PDF reader already installed on your device. An example is Adobe Acrobat Reader or any other software that can open

To download the Ushahidi User Manual as PDF on your local machine, you can download individual pages (sections) or the entire documentation.

How to download an individual page/section

Video setup guide

Setup guide

1. Click on Platform User Manual or [Mzima] User Manual to open the documentation.

1. Open the page/section of the documentation you want to download e.g. Setting up a deployment. Click Export as PDF.

1. Click the Print or Save as PDF button in the upper right corner to open your browser's Print menu.

1. Preview the page, customize the print options as preferred, and click the Save button.

1. Type your preferred file name and save it to your local machine by clicking the Save button.

How to download the entire documentation

Video setup guide

Setup guide

1. Click on Platform User Manual or [Mzima] User Manual.

1. Click Export as PDF.

1. Click the All pages button in the bottom left and wait for the document to load.

1. Click the Print or Save as PDF button in the upper right corner to open your browser's Print menu.

1. Customize the print options as preferred, and click on the Save button.

1. Type your preferred file name and save it to your local machine by clicking the Save button.

In order to start using the Ushahidi Platform you may choose between:

• Creating your deployment online: This is done on Ushahidi's hosting service, which you may find at https://ushahidi.io/create . This doesn't require technical knowledge on your side.

• Installing it yourself: This assumes that you have a suitable server or networked computer and some time to go through our published instructions. Some technical familiarity with your computing environment is needed.

Installing it yourself

Better development stack

Ushahidi mzima platform Backend API is built on PHP stack: as with v3 platform, we’ve isolated the core logic of the platform standalone Entity and Usecase classes. The mzima platfrom API uses the Laravel framework.

The user interface of Ushahidi mzima platform is a separate app with a codebase that has the web client and mobile client in it. The web client is built with Javascript, HTML + CSS using modern Angular 14+ and the Angular material library for styling. The mobile client is built using the Ionic framework.

What’s new (and improved)?

Largely similar to v3:

• Dependencies are properly managed and easier to update or replace needed.

• We’re using our own API to build the app, it gets first class support.

• You can work on just the UI without delving into the API code

• Modern libraries mean they’re still being supported, we don’t have the burden of supporting legacy libraries ourselves.

Code is easier to customize

• It’s more structured making it easier to find what you want - architectural changes still ongoing

• It doesn’t repeat itself so a change can be made in one place, not need to be copied everywhere else - architectural changes still ongoing

• UI is isolated to the backend API, allowing work on just the UI without having to delve into the API code

The stack

• Back-end: Linux, PHP, Apache/Nginx, MySQL or PostgreSQL

• Front-end: Angular, Javascript, Html, CSS. Built with NodeJS. Using Leaflet for mapping, and a collection of other frontend libraries

One of the first things you should do as the admin of your new deployment, is customize certain settings based on the project you’re working on. This section describes how to change your general and map settings, as well as how to configure data sources, manage surveys and categories.

3.1 Accessing your deployment

3.2 General Settings

3.3. Surveys

3.4 Data Sources

3.5 Categories

The general settings page allows you to set the basic appearance of your deployment. To access General Settings, do the following.

On the sidebar, click on Settings

This will take you to the General Settings. You can always click on the General card to take you back to this page if you move on to some other settings page.

Add the following details to the form on the page

• Site Name: This changes the main title of your deployment, and is typically the title of your project. You can change this at any time.

• Site Description: This tagline appears below your deployment name, and should be a one or two sentence overview of what your deployment is about.

• Deployment logo: Your deployment logo will appear on the right hand sidebar on your homepage, under your deployment name and above your deployment description. If you’d like to remove it once it has been added, just hit the Delete Logo button

• Contact Email Address: This optional contact email will be displayed publicly to visitors of your deployment.

• Site Language: You can update the default language of your deployment. This will update the labels within your user interface, and will update the layout of the deployment if you select a language that reads from the right to the left.

• Private deployment: Ticking this checkbox makes your deployment and it’s data only accessible to registered users(with the correct privileges) on your deployment, who must sign in for access.

• Disable user sign up: Ticking this checkbox disables the registeration feature preventing people from signing up into your deployment.

Configuring map settings

You’ll also need to configure your map settings from this page. Your map settings allow you to select the type of base map you want for your project. You can configure the following:

• Default base layer: Currently, the platform only offers Openstreetmap as a map provider. Plans are being made to add additional map providers.You can choose between the map, satellite and humanitarian views. This will determine the style your map will display as on your homepage.

• Default latitude and Default longitude: Dragging and dropping the blue pointer on the map automatically fills in these two fields. In the event that you have latitude/longitude values, you can also type them in and the pointer on the map will automatically update to match the points entered.

• Default zoom level: Zooming in and out of the map using the small menu bar on the left top hand side of the map will automatically set a value in this field. You may also optionally set the zoom level by manually adding a figure in this field and your map will update to match.

• Combine nearby posts: This checkbox is checked by default, meaning that posts near each other will be bundled together and denoted as a single point on the map with a number to show how many posts they are. If you uncheck this option, each post will appear as a single point on the map.

• Map Precision Level : This allows you to indicate the level of exactness for locations on the map.

From the homepage on ushahidi.com, click on the Create a Deployment button. This should take you to http://ushahidi.io/create.

Manage Cookies

• You can limit what cookies end up on your computer or mobile device by enabling/disabling them.

• Click on details to have a basic understanding of what each cookie entails before selecting, and click on About to learn more about cookies.

• Click on Deny or Allow Selection or Allow All when done.

Filling out your deployment details

• Deployment Name: You can give your deployment any name

• Deployment URL: Each deployment will have a unique web address. No two deployments can have the same web address. Once created, this CANNOT be changed, so be sure to countercheck the web address set is one you’re okay having permanently.

• Once you’re done, click on Continue.

Filling out the organization detail fields

• Organization name: This is the name of your organization, assuming it's different from the name of your deployment

• Size of the organization: How many people are working with you in your organization?

• What are you using Ushahidi for: Select the appropriate category that matches what you will be using your deployment for

• Once you’re done, click on Continue.

Fill out your account details

• Name: This will appear alongside your activity on the deployment

• Email address: You’ll use this email address to log into your deployment and receive notifications

• Set a secure password that will be used to access this deployment.

• Agree to our Terms and Conditions

• Once you’re done, click on “Create Deployment”

3.1.1 Log in

Log in: If your deployment URL is my-deployment.ushahidi.io, Click on the Log in link in the sidebar of your deployment as illustrated below.

Password and registration:

For Open Source deployments, the default install will create a user admin, with password admin123. Be sure to edit this user’s password once you’re logged in.

For ushahidi.io deployments, enter the email address and password you used to register your deployment, and the password

Note: You can use EITHER an email address OR username with a corresponding password to log into your deployment.

3.1.2 Create an account

If you don’t have an account already, you can create one by clicking on Sign Up and filling in the required details.

When you create a deployment you become an admin by default, but if you are another member with access to the same deployment, you’ll will be able to log in and perform basic actions on the platform, but won’t have much privilege within the platform until an administrator upgrades your access level.

3.1.2.1 Your Account details

Once you’re logged in, you can access and change your account details at any time. To do so, click on your account favicon at the top right hand corner of your deployment as illustrated below.

A pop up will appear on your screen once you select Account Settings. Make changes to your profile as desired, then click on Save & Close

3.1.2.2 Notifications

As a registered and logged in user, you can set up notifications on Saved Searches and Collections. This means that any time a post is added to a saved search/collection, you will receive an email or phone notification - the notification feature is still in development on the mzima platform.

You can manage(turn these notification on or off) by:

Clicking on your account favicon at the top right hand corner of your deployment as illustrated below.

Then, Click on Notifications tab from the modal popup.

A list of all notifications you’ve signed up for will appear, with the option of turning them on and off. You’ll also be able to determine the email address or phone number through which you would like to receive notifications. You must have SMS configured to enable.

You can also add additional contacts to receive notifications via email/phone.

3.1.3 Logging out

To log out of your deployment, click on the log out icon at the top right hand corner of your deployment as illustrated below.

You should be successfully logged out of your deployment, and redirected to the homepage.

What is Survey?

A survey defines critical aspects of a post’s structure and permissions. For example, a post’s “survey” defines which fields are available for contributors to complete, and who can see it when it’s published.

This section will show you how to create and manage surveys on your deployment.

The setup in this guide is demonstrated in the below video as well. You can watch and follow the guide at the same time!

Pre-Requisites

Before configuring the survey on your platform, you'll need to install Ushahidi's platform and set up your deployment. You can complete this task by referring to the following resources:

• Installing Ushahidi

• Setting Up a Deployment

Make sure you are logged in to your deployment page.

Setup guide

Video tutorial for accessing surveys

To access the Surveys configuration page, on the sidebar, click on Settings

Then, click on Surveys

3.3.1 Building Surveys

By default, each deployment has a Basic Post survey, which can be deleted or modified as needed. To create a new survey:

Video setup guide for Building surveys

• Click on Add Survey as shown below.

• In the upper right corner of the survey form, you will see the default language that your deployment is currently in. Check Chapter 3.3.2 on how to change a survey's default language

• Fill in the required details:

  • Survey Name: Try being as specific as possible when creating your survey name so that users will understand what they are selecting when creating new posts

  • Description: Provide a brief description of what kind of data you’ll be collecting with this survey

  • Fields + Tasks: See below for details on how to add fields and tasks into your survey.

  • Click on save once you're done building your survey.

Video setup guide for duplicate surveys

To duplicate a survey

On the surveys settings page where you have a list of surveys:

• Click on the bulk actions button

• Check/select the survey(s) you would like to duplicate

• Then click on the duplicate button or icon.

3.3.1.1 Fields

Video setup guide for managing fields

Each survey you create will have a title and description field by default. It's important to note these fields can be edited, but cannot be deleted.

Different Types Of Field

• Short Text: Short Text field is designed for brief, single-line responses—typically a sentence or less. This field is particularly useful when you need concise information.

For example, in a flood report survey, you might ask a simple question like: "What is the estimated water level during the flood?" Here, a Short Text field would capture specific, brief inputs like "3 feet" or "1 meter."

• Long Text: Long Text field is ideal for capturing more detailed responses, such as paragraphs or multiple sentences. This field is perfect when you expect users to provide in-depth feedback or explanations.

For example, in a flood report survey, you might ask: "Can you describe the impact of the flood on your home and surroundings?" In this case, the Long Text field would allow respondents to give a detailed response like: "The flood caused significant damage to our home. The water reached the first floor, destroying furniture and appliances. Roads were also submerged, cutting off access to emergency services for several days."

• Number(Decimal): This field is designed to capture numerical inputs, which include decimal values. This field is useful when precise numerical data is needed.

For example, you might ask: "What was the total cost of flood damage in dollars?" Here, the Number (Decimal) field ensures respondents can enter exact monetary figures like 1500.75, making it easy to record detailed financial data.

• Number(Integer): The number (Integer) field is designed to capture numerical inputs, which are whole numbers. This field can be useful for the answer which will obviously be a whole number.

For example, you might ask: "What is your age?" Here, the Number field ensures respondents can enter the whole number as inputs.

• Location: This field allows users to share geographic data. This field can provide a map interface, enabling respondents to select their location or manually input latitude and longitude coordinates. This is particularly useful when collecting precise location data.

For example, in a flood report survey, you might ask: "Please provide the exact location of the flood impact." When using the Location field, a map will appear in the survey. Respondents can either click on the map to mark their location or can manually move the cursor on the map for exact latitude and longitude values, such as 28.6139° N, and 77.2090° E. This data is valuable for creating accurate, location-based reports.

• Date: This field allows respondents to select a specific date, providing them with a calendar interface where they can adjust the month, date, and year according to their requirements. This is particularly useful when you need time-related information.

For example, in a flood report survey, you might ask: "When did the flooding start in your area?" Using the Date Field, respondents can open the calendar, navigate through the months and years, and select the exact date. The default value will be the current date when the form is filled, but users can easily modify it to reflect the appropriate date of the event.

• Date and Time Field: This allows respondents to select both a specific date and the exact time using a calendar and time picker interface. This field is useful when you need precise information that includes both the day and the time of an event.

For example, in a flood report survey, you might ask: "When did the floodwaters start rising in your area?" Respondents can select the date from the calendar and then adjust the time by choosing the exact hour and minute, such as August 15, 2024, 03:30.

• Select: This field provides respondents with a set of predefined options to choose from. These options are created by the admin. Respondents will see a drop-down arrow, which they can click to reveal the available choices. Only one option can be selected from the list.

For example, in a flood report survey, you might ask: "What is your preferred method of receiving flood alerts?"

In the Select Field, respondents can click the drop-down and see options like:

SMS

Email

WhatsApp Message

The respondent can then select the one option that best fits their preference.

• Radio Button(s): The Radio Buttons Field is similar to the Select Field, but the key difference is that all options are visible on the form itself, rather than being hidden in a drop-down menu. Respondents can view the options directly and select only one.

For example, in a flood report survey, you might ask:

"What is your current living condition after the flood?"

In the Radio Buttons Field, the options might appear like this:

Staying at home

Temporarily relocated

In a shelter

With relatives

The respondent can select the most accurate option by clicking the corresponding radio button.

• Checkbox(es): These allow respondents to choose one or more options from a predefined set. Unlike radio buttons, where only one option can be selected, checkboxes enable users to select multiple options if applicable.

For example, in a flood report survey, you might ask:

"Which resources do you currently need?"

The Checkboxes Field could have the following options:

Food

Water

Medical Supplies

Shelter

Clothing

Here, the respondent can select multiple options based on their needs, such as both Food and Water.

• Related Post: The Related Post Field allows you to create a connection between different surveys by linking relevant posts. This is particularly useful for cross-referencing data from various surveys. However, it’s important to note that only posts that have been published will appear in the search results when linking; posts that are "Under review" will not be visible for selection.

For example, in a flood report survey, you might want to relate a previous disaster preparedness survey to understand how preparedness impacted the flood response. Using the Related Post Field, you can link the two surveys, enabling easy access to relevant data across surveys.

• Image: The Image Field allows users to upload images to the post, with a maximum file size of 10.00 MB. To add an image, respondents can click the Add photo button and select the desired image from their device. Additionally, there's an option to include a caption for the image, allowing users to provide a brief description or context for the uploaded photo.

For example, in a flood damage report, respondents could upload images showing the extent of the flood's impact and add captions like: "Floodwaters reaching up to 3 feet in the living room."

This feature is particularly useful when visual documentation is needed to support the report.

• Embed Video: The Embed Video Field allows users to embed videos from platforms such as YouTube or Vimeo directly into the post. Respondents simply need to paste the video link (URL) into the provided field. This feature is useful for sharing visual content that supports the post or survey data.

For example, in a flood damage report, respondents could include a YouTube video showing the flooding in their area. This allows for more dynamic and detailed reporting, providing a clearer visual context alongside written information.

3.3.1.1.1 Adding Fields

You can add as many custom fields to your survey as you see fit. To add a new field, click on the Add Field button.

A pop-up box with a list of different field types will appear on your screen. Choose whichever one will work best for the type of data you are trying to capture.

Add the following details for which ever field type(s) you select:

• Name: This is what is displayed as a label for your newly created field

• Add field description (optional): A visual editor should appear below, you may add help text that provides additional details about this field.

  • Add some text in the description-editor, format it however you want to, and as long text as you want to.

• Required: If set to yes, post submission will be only be successful once this field has been filled out. If set to no, post submission will be successful even if it has not been filled out.

• Make responses private: This allows limiting access to responses to this field to specific users.

• Default Value: You can set a default value displayed every time someone is creating a new post. example, a survey asks whether you want to subscribe to a service, and it has a default value of 'No'. If you submit without changing this value, the default value will be submitted as 'No' when you save the survey. If you change to 'Yes', the value that will be submitted will be 'Yes'. That's the value that will be submitted when the survey is saved. Note: For fields where it's possible to add a default value (all field-types except "image", and "categories"), the default value box should be displayed with no toggle-switch

• Field Options: This appears in cases where you’re creating a checkbox, select or radio button field. You can add as many options as you would like.

• Once you’re done, click on Save.

Note that, the description should have the same formatting as it did in the field description editor. To confirm this:

• Add a new post to this survey you just created

• Save the post

• Go to data view

• Select the post you added and select "edit"

• The field description you added will be visible.

• The description should have the same formatting as you did in the editor

3.3.1.1.2 Editing Fields

Video Setup Guide for Editing Fields

To edit an existing field:

• Select the desired custom field by clicking on it

• Edit the fields (as described in the section above on Adding fields) as desired.

• Click on Update when done.

You can also change the position of existing fields by dragging the field with the scroll icons to the left of every field as shown below.

3.3.1.1.3 Deleting Fields

Video setup guide for Deleting Fields

To delete an existing field

• Click on the trash icon adjacent to the field you'd like to delete.

• A pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete the field

  • Click on Delete to delete the field

  • If you’d like to cancel the field deletion process, click on Cancel

3.3.1.2 Tasks

You can organize your survey into “Tasks”, allowing a deployment to add fields related to actions that need to be taken, like translation or verification. These groups of tasks are visible to specified users and can be marked as ‘complete.’ For example, if a particular survey requires verification upon submission, you can design a task to ensure your team knows the post needs to be verified before publishing. The task could include fields like whether the information was verified or not, who verified the information, how they verified it, and when they verified it. After verification, the task can be marked as complete and the post can either be moved to the next task if necessary, or published.

3.3.1.2.1 Building Tasks

Video setup for Building Tasks

To add a new task:

• Click on Add Task on your survey creation/edit page

• A small pop up box will appear, prompting you to give your task a name

• If you’d like to make this task required before post submission, switch on the Require this task be completed before a post can be visible to the public toggle. This means that, a post will not be published until this task is marked as complete

• Click on Add

Once set up, you can duplicate your task as follows. Adding task fields

You should be able to add fields to tasks in the same way that you add fields to a survey.

Please refer to the Fields section of this manual for details on how to add, edit, and delete task fields.

3.3.1.2.2 Configuring tasks

Video setup for Configuring tasks

To make additional configurations to your task, click on the Configure tab

Set the following options

• _Required: _When set to yes, this task must be set as complete for successful post-submission

• Task is only for internal use: This limits the visibility of this task during submission only to teams with permissions to manage posts on your deployment i.e only internal team members will be able to submit responses to this task

• _Show this task to everyone when published: _This limits the visibility of task responses when viewing submitted posts if not enabled i.e. it limits the visibility of responses to tasks to internal teams only.

This is what it would look like when applied to your survey form later on:

3.3.1.2.3 Editing Tasks

To edit an existing task:

• Scroll down to the desired task

• Make changes as desired, e.g changing the task name, description, and/or making a task required or not

• When done, click on Save at the bottom of the page

3.3.1.2.4 Deleting Tasks

Video setup for deleting tasks

To delete an existing task

• Scroll down to the desired task

• Select Delete Task button

3.3.2 Translating Surveys

Once the survey form has been created and all the required fields have been filled, you can translate the survey into other languages if you want to. Below are a video and written setup guides to help you.

Note: You can add more than one language

Written Setup Guide

• Click on Add translation at the upper right-hand corner of the survey form.

• A pop-up module will appear on your screen, select the language(s) you want to translate to using the checkboxes beside the language names.

Then:

• Click on Add to finish.

• You will be redirected to a survey form with the translatable content in the default language and fields where you can add your translations

• On the empty fields, translate the survey details into the chosen language e.g in the above image the default language is English and the added language is French.

On the survey, you will then be able to see the available languages that the survey has been translated into.

Similarly you can see this translate dropdown to select a language to translate to on the post edit form in the data view:

3.3.2.1 Translating Fields

To translate the added fields on your survey;

• Scroll down to fields.

• Select the desired custom field by clicking on the edit button icon that is on it.

• A pop-up module will appear. Translate the field details to the chosen language.

Translate the remaining fields that you added.

3.3.2.2 Translating Tasks

To translate tasks:

• Scroll down to tasks.

• Translate the task details. You should be able to translate the task fields in the same way that you translated the fields in the surveys. Please refer to the Fields section of this manual for details on how to translate task fields.

• Click Save when all is done.

3.3.3 Configuring Surveys

You can add additional configurations to your survey e.g setting a survey color etc. To do so, click on Configure on the top of the survey editor.

Configure the settings to suit your needs

• Require posts be reviewed before they’re published: When toggled on, posts submitted on your deployment will not be made public i.e accessible to anyone beyond your internal team, until it is reviewed ( It will remain in draft). Setting this option off will automatically publish all posts submitted on your deployment.

• Hide author information: When toggled on, this option hides author information e.g phone numbers, twitter handles and email addresses of people who submit posts to your deployment from the public. Note: logged in users with permission to manage posts will still be able to see author information.

• Hide exact location information: When toggled on, this option hides the exact location of posts on the map. Only the people with the permission to edit will be able to see exact locations, those without permission will only able to see rounded locations. The locations will be accurate to 0.1 km.

• Hide exact time information: When toggled on, only people with permission to edit responses will be able to see exact time submitted. Other people will see only the date.

• _Who can add to this survey:_You can limit submission of posts to your survey by roles. By default, surveys are open to the general public for submissions, and not limited to internal roles.

• Color: Select a color or input a specific hex value to choose which color will be associated with this survey. Pins on the map will match whichever color you select.

• Select default language for this survey: Click on the dropdown menu to choose the default language. This will be changing the language of the deployment that is currently in.

• Click on save once your configuration options are complete

3.3.4 Sharing Surveys

Ushahidi provides the ability to Share your survey across multiple platforms. Share via:

• Web address: Copy and paste this link to direct people to your survey form

• Facebook: Share the survey form on Facebook

• Twitter: Share the survey form on Twitter

• Embed: Copy and paste this HTML block of code to embed the survey form on any site across the web

3.3.5 Editing surveys

To edit a survey:

• Click on a survey from the list of surveys on your page.

• From here, change your survey details as desired then click on Save.

3.3.6 Deleting surveys

On the surveys settings page where you have a list of surveys:

• Click on the bulk actions button

• Check/select the survey(s) you would like to delete

• Then click on the delete button or icon.

A pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete the survey and all its data.

• Click on Yes, delete to delete the survey

• If you’d like to cancel the survey deletion process, click on No, go back. Note: Once you delete your survey all its data and posts will be deleted . This cannot be undone, so take caution when you perform this action.

There are many ways to enter posts into your Ushahidi deployment other than from the deployment itself. This section shows you how to configure all the possible data source types.

To access the data sources configuration page, on the sidebar, click on Settings

Then, click on Data Sources

You should get a full list of data sources as shown below

In this section you will learn how to configure different data sources to your Ushahidi deployment.

3.4.1 Email

3.4.2 Gmail

3.4.3 Frontline SMS

3.4.4 Vonage(formely NextMo)

3.4.5 SMSSync

3.4.6 Twilio

3.4.7 Twitter

3.4.8 Africas Talking

This section allows you to set up the platform to receive emails from users. Before getting started, make sure that you have an email account set up on Gmail, Yahoo or any other service provider. Make sure that you have IMAP/POP enabled (For more information on these two protocols, visit this website. Instructions on how to enable the IMAP/POP settings in your email can be found here

Gmail settings: Follow this guide to enable IMAP from external clients with Gmail. Keep in mind: There are a few settings you need to configure so that Ushahidi can pull from a Gmail account.

• Step 1: Check that IMAP is turned on

  • On your computer, open Gmail.

  • In the top right, click Settings See all settings.

  • Click the Forwarding and POP/IMAP tab.

  • In the "IMAP access" section, select Enable IMAP.

  • Click Save Changes.

• Step 2: Check that Two-Factor Authentication is turned on One needs to have Gmail's Two-Factor Authentication enabled. Visithttps://www.google.com/landing/2step/ if you do not have it enabled for your account.

• Step 3: Create an App password This is a 16-digit passcode that gives a non-Google app or device permission to access your Google Account. (Google Docs here:https://support.google.com/mail/answer/185833?hl=en-GB)

  • On your computer, open App passwords

  • When prompted for "Select the app and device you want to generate the app password for":

  • Select “Mail” under the drop-down for “Select app”

  • Select “Other” under the drop-down for “Select device”

  • When prompted for text input, enter your Ushahidi deployment name

    (e.g. The name of my deployment is Free Media, I’ll enter “Ushahidi Free Media ”).

  • Copy the password to your clipboard that is automatically generated and save it somewhere (we would need this later).

Yahoo settings: Yahoo

Email setup on Ushahidi platform

To get started with email the setup, click on the add source button on the top right as shown and select Email.

Input the following email account settings

• Incoming server type: You have two options to select from, POP and IMAP. We recommend using IMAP if possible because it’s the best way to make sure you can see all your mail at any time on all of your devices

• Incoming server: Enter the address of the server where your email services are hosted. E.g mail.yourwebsite.com and for Gmail: imap.gmail.com

• Incoming server port: Enter the port that your email account uses for incoming emails. This is also provided by your service provider and depends on the use of SSL(Secure Sockets Layer)/Transport Layer Security(TLS) or not. As a standard rule;

  • Enter 993 (Since we’re using IMAP) for Gmail.

  • POP uses port 110 , but SSL/TLS encrypted POP uses port 995

• Incoming server security: You have 3 options to choose from to enhance secure connection to your email mailbox, depending on which is supported by your email service provider.

  • None

  • TLS - Read more on Transport Layer Security

  • SSL - Read more on Secure Sockets Layer for Gmail

• Incoming user name: Enter the email address you want to use to receive emails e.g sample@youremail.com. We recommend setting up a separate email address for this purpose, preferably one that has a lot of available space to avoid the account getting full in a short time, especially if the platform will be receiving a lot of submissions via email.

• Incoming password: Enter the password of the email account inserted above. Enter the “App password” generated above for the gmail account.

Next:

• Click on Save and this data source’s settings will be saved. Unstructured posts from email will now be pulled into the platform.

• If you’d like to edit your email configuration, simply click on the the email data source to see the edit form, and make your changes.

• If you no longer want the email data source simply click on the data source as if you want to edit it and the use the delete button.

Note: Reports coming via email will take a while before they reflect on the platform because there is a “job” that needs to be run in the database and those jobs run every 10 minutes or so.

This section allows you to set up the platform to receive and send emails through a connected Gmail account via the API. Before getting started, make sure that you have an email account set up on Gmail. Note: If you're self hosting the Ushahidi platform, the Gmail Provider makes use of the server-side flow when making a request to Gmail API, and must be authorized using OAuth 2.0 Credentials.

Follow this guide to create the OAuth 2.0 Credentials (Client ID and Client Secret) with Gmail. Keep in mind:

• Select "where you will be calling the API from" as Other UI.

• Select User data as the data type to be accessed.

• Select your application type as TVs and Limited Input devices.

• There's a need to set up a consent screen.

To get started with Gmail set up on the Ushahidi platform, click on Gmail from the drop down as shown below.

Input the following email account settings

• Email Address: Enter the Gmail address you will be receiving and sending emails with.

• Fetch Email From: Pick the date you want to start fetching messages from.

• Client Id: Enter the Gmail client id gotten from the OAuth credentials.

• Client Secret: Enter the Gmail client secret gotten from the OAuth credentials.

• Redirect URL: Enter the redirect URL from the OAuth credentials. The default value set here is urn:ietf:wg:oauth:2.0:oob and in most cases should be left this way.

• Click on Save and this data source’s settings will be saved.

The below setup will be available to both the hosted and self-hosted users.

• Next, Scroll up and click on Connect your Gmail Account and this will show a google prompt to authenticate your Gmail account.

• Follow the prompt through and click on Allow to be presented with the list of Gmail accounts that you have.

• Grant permission by selecting the Gmail account that you would like the Ushahidi platform to access.

• This will display an auth code.

• Please copy the provided code, switch back to your Ushahidi application, and paste/enter it on the opened modal:

• Enter the point in time that you would like the Ushahidi platform to fetch messages from your inbox.

• Click on Authorize to save the auth code and date entered.

• A message will be displayed in your deployment to indicate that your account is connected, messages from Gmail will now be pulled into the platform via the API.

• To disconnect your account, simply click on Disconnect your Gmail account to stop all messages from being fetched from your inbox.

NB: All messages that were previously fetched will not be deleted from your deployment.

• To enable/disable the email data source, simply click on the green toggle and click on save.

Vonage is a cloud-based SMS API that lets you send and receive a high volume of messages to mobile phones in any country at wholesale rates.

NB: You need a nexmo account to be able to configure this as a data source. To sign up, go to (https://dashboard.nexmo.com/sign-up)

To get started with Nexmo set up,

• Log into your Vonage Dashboard https://dashboard.nexmo.com

• If you haven’t already, you’ll need to buy a number that you will use to receive SMS messages from.

  • Click on Numbers on the top menu bar on your Vonage dashboard

• • Click on Buy Numbers

• • Set the desired criteria of the phone number you’re looking to use

• • • Select the country in which the SMS Number will likely be operating in

    • Select the features of this phone number(SMS only, Voice only or SMS & Voice)

    • Select the type of phone number it will be (Mobile, Landline, Toll free)

  • Click on search. A list of available numbers based on the criteria set above will appear.

• Click Buy on the number you’d like to use.

• Once you have a phone number, note it down as you’ll need it to configure your data source later on.

• You’ll need to grab your API credentials from your nexmo settings page.

• Pick your API KEY and API SECRET from the API Settings section.

• Go back to your Data source settings page on your deployment

• Click on the drop down icon on the right to get to your Nexmo configuration page

• Enter the following details, which you got earlier from your Nexmo Dashboard

  • From: Enter the phone number you will use to receive SMS messages from your nexmo account

  • API KEY: Enter the API key retrieved from your nexmo settings page.

  • API SECRET: Enter the API secret retrieved from your nexmo settings page.

• Click on Save **and this data source’s settings will be saved. Unstructured posts from SMS will now be pulled into the platform from Nexmo.

• To enable/disable the Nexmo data source, simply click on the green toggle.

• If you’d like to edit your Nexmo configuration, simply click on the drop down icon on the right while on the data sources list page and make your changes.

Nexmo setup for Ushahidi Platform SMS connectivity

Go to https://dashboard.nexmo.com/settings where you can set up the webhook. This is where we can make Nexmo aware of the existence of your Ushahidi deployment and help them connect with each other. Enter the sync URL i.e “https://yourdeploymentname.api.ushahidi.io/sms/nexmo” on the inbound SMS webhook field as shown below and save changes.

SMSsync is a simple, yet powerful SMS to HTTP sync utility that turns any Android phone into a local SMS gateway by sending incoming messages (SMS) to a configured URL (web service).

Please note that SMSsync works on any SMS-enabled device running Android 2.1 and above.

• Once you have downloaded it, click on install to save it on your phone.

• Open up the SMSSync Application on your android device, click skip or swipe left, and click done to continue.

• On the incoming messages screen, click on the arrow at the bottom right corner to enable SMSsync.

• Once you have enabled SMSsync, you will be redirected to the integrations screen. Start the SMSSync Service to start fetching messages in your app.

• Click on the custom web service to configure SMSsync with your deployment.

• Manage custom web services screen will open, you’ll note that you can manage multiple Sync URLs on the app.

• To add a new Sync URL, tap on the Add icon on the actionbar. An input dialog should open.

Configuring SMSsync datasource on your Ushahidi Platform

• Open your deployment i.e name.ushahidi.io, go to datasource configuration in your setting page.

• Click on the drop down icon on the right as shown

• Follow the instructions given to you below.

• You will need the Sync URL to configure SMSSync.

• Set a SMSSync secret key for security purposes.

• Click on Save.

• To enable/disable this datasource , simply click on the green toggle to accept survey submissions.

• Click on the toggle to import your messages' response to a survey.

• Select the survey you wish to import your messages to.

• Select which field should be assigned to populate the data from SMSsync.

SMSsync setup for Ushahidi Platform SMS connectivity

• Go back to the input dialog on your SMSsync App and add the following details;

• Title for the custom service: This can be the name of your deployment or any title you see fit

• Custom web service Url: Enter the Sync URL in step 2 from your deployment as shown in the 'Android settings' image above i.e "https://yourdeploymentname.api.ushahidi.io/sms/smssync".

• Secret key: Make sure you enter the exact key as the one you entered in your deployment android setting as shown in the 'Android settings' image above.

• Once you enter your secret key, you are done with the configuration, do not change the rest of the settings.

• Click ADD or test integration to save the new entry.

Nb:The secret key should be presented as string of any characters without spaces. Enter a comma separated value for the keyword(s). These keywords will be used by SMSsync to filter incoming SMS and pending messages to the Sync URL you are adding. As of v2.0.2. You can now add Regular Expression code for filtering. This means, it can either be CSV or RegExp. It cannot be both.

Note: Version 2.5 or higher supports basic auth credentials in the URL, e.g. https://username:pass@example.com/api-v1/add-record/.

• You will now need to start the SMSSync Service to start forwarding messages to the platform. To start the SMSSync service

  • Make sure that you have added and enabled(checked) the Sync URL you added above.

  • On the integration screen, tap on the Start SMSsync service to start the service if you had not enabled it.

You should be all set to work with SMSSync and Ushahidi now. Unstructured posts via SMS will now be pulled into the platform.

If you’d like to edit your SMSSync configuration, simply click on the drop down icon on the right while on the data sources list page and make your changes.

For more details on how to manage messages within SMSSync, see configuration instructions on the SMSSync Website

Twilio allows you to programmatically make and receive phone calls and send and receive text messages using its web service APIs.

NB: You need a Twilio account to be able to configure this as a data source. To sign up, go to **[_https://www.twilio.com/try-twilio**_](https://www.twilio.com/try-twilio)

To get started with Twilio set up,

• Log into your twilio account.

• You’ll need to buy a number to use. Click on the hashtag icon

• Click on the red "Plus" icon.

• Select the desired criteria for your phone number In the number selection/purchase screen

  • Select the country where you need a phone number. This is the number that people will use when sending a report through SMS.

  • Location/Number: You can search numbers by digits/phrases or by location. This is optional.

  • Capabilities (Voice, SMS, Fax, MMS): Make sure you tick the "SMS" checkbox. We want to make sure Twilio only shows us numbers with SMS capabilities. If it can't be ticked/clicked, then it means that Twilio doesn't have any numbers with SMS capabilities in that country.

• Click on **_Search**_. A list of available numbers with their rates based on the criteria set above will appear

• Click Buy on the number you’d like to use.

• You will be shown a screen like this one below where they confirm all capabilities, the number, and other details.

• Click the buy button at the bottom right hand of the screen to purchase your number.

• Once you have a phone number, note it down as you’ll need it to configure your data source later on.

Configuring Ushahidi Platform to use your Twilio phone number

First, we need to get the following information from your Twilio account:

• Phone Number: the number you just purchased. If you forgot it, you click the "Hashtag" icon in Twilio again to see your available numbers.

• Account SID

  • Go to https://www.twilio.com/console/

  • You will see a panel like the one below with details about your project. Get the Account SID from it (we've highlighted it in the screenshot as a reference)

• Auth Token

  • In the same panel as the account SID, you will see a "view" link next to "Auth token" as shown on the diagram above.

  • Click it, and it will display your account's auth token.

Next, with the Account SID, Auth Token and Phone number you just obtained:

• Go to your Datasources settings page on your Ushahidi deployment.

• Click on the drop down icon on the right as shown

• You will see a list of fields like this one

• Enter the following details, which you got earlier from your Twilio Account

  • From: Enter the phone number you got from Twilio.

  • ACCOUNT SID: Enter the account SID of your Twilio account

  • AUTH TOKEN: Enter the Auth Token retrieved from your Twilio account Dashboard page

  • SMS Auto Response: This will be sent automatically when a user sends a message to your Twilio number. You could use it to provide reference information, like thanking the user or just confirm receipt.

  • Click on Save **and this data source’s settings will be saved. Unstructured posts from SMS will now be pulled into the platform from Twilio.

• To enable/disable the Twilio data source and choose which survey to import to, simply click on the green toggles.

• At this point, your Twilio setup in Ushahidi Platform is ready to use but we need to do some follow up tasks in Twilio to connect both of them.

Twilio setup for Ushahidi Platform SMS connectivity

Go to https://www.twilio.com/console/phone-numbers/runtime/twiml-apps where you can create Twiml apps. This is where we can make Twilio aware of the existence of your Ushahidi deployment and help them connect with each other.

• Click on the red "+" button to create a new app. You will see a screen like the one below.

Fill in these details;

• Friendly name: Write down a name that helps you remember what this app does. We usually choose the deployment name as the "friendly name" in Twilio.

• Messaging: In this **section you will need to add your deployment's Twilio endpoint URL. This is the API Url to your deployment + the endpoint to connect to.

  For Ushahidi.io deployments, the rule is always the same. Given a deployment with the following url "https://**yourdeploymentname**.[ushahidi.io](http://ushahidi.io)" + the API Url will be = "https://**yourdeploymentname.api**.[ushahidi.io](http://ushahidi.io)".

  • Follow this formula to get your Request URL:

    • Your deployment URL: "https://**yourdeploymentname**.ushahidi.io"

    • The API URL: "https://**yourdeploymentname.api**.ushahidi.io"

    • The Request URL then would be "https://yourdeploymentname.api.ushahidi.io/sms/twilio". is what you will enter in the "Request URL" field.

• After you are done with adding Messaging and friendly name, you can click the red "Save" button.

Configure your phone number to send messages to Ushahidi platform

• Go to your list of active phone numbers and click on the number you purchased https://www.twilio.com/console/phone-numbers/incoming

• Click on your number.

• Scroll down and you will see a form like this one.

• In the configure with field: Select TwiML App

• in the TWIML APP field: Enter the Friendly name you created above for your deployment. This will ensure that when you get an SMS, Twilio sends a request to Ushahidi platform to save the message.

Trying this out

Checking that Twilio gets the message

• Send an SMS to the phone number you purchased and configured (ie from your own phone).

• You can validate that messages are getting to Twilio by going to the Programmable SMS logs https://www.twilio.com/console/sms/logs

• You will see the messages your Twilio number has received and sent in the list

• The list will look like this. You can click on the red link under "Date" to see the details of each message.

• Example of a single message below.

Checking that Ushahidi Platform gets the message

• Go to the Ushahidi Platform

• Go to the data view

• You should see the messages you sent in the data view list

This section allows you to configure Africa's Talking as a data source and receive SMS messages as unstructured posts in your Ushahidi deployment.

Setup Africa's Talking Data Source in Ushahidi

1. Login to Ushahidi.

1. Click on Settings -> Data Sources

2. Click Add source

1. Select Africa's Talking

1. Enter your Username, API Key, and SMS Short Code, and then click Save.

Setup Ushahidi Callback in Africa's Talking

1. Login to Africa's Talking Dashboard and click on app

1. Click on SMS -> Callback URLs -> Incoming Messages

2. Enter the Ushahidi's callback URL and click Submit.

The URL is your deployment backend's API URL, ending with "/sms/africas-talking"

e.g. https://quakemap.api.ushahidi.io/sms/africas-talking

In some cases, we’ve seen large groups of people teaming up to work on managing data on Ushahidi deployments. This section describes how to create and manage custom roles and users on your deployment.

4.1 Roles

• Adding Roles

• Editing Roles

• Deleting Roles

4.2. Users

• Adding Users

• Editing Users

• Deleting Users

Video setup guide

Written setup guide

To access the User management page, on the sidebar, click on Settings

Then, click on Users

Then:

• You’ll be redirected to a page with a list of all existing users on your deployment

• If you are an ushahidi.io user, you should see the the user you created on set up listed on this page. If you are an ushahidi open source user, every installation comes with a default username: admin and password: admin123

• From here, you can search for users either by name or by custom role

4.2.1 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.

4.2.2 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.

4.2.3 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 single 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 Yes, delete to delete your user

• If you’d like to cancel the user deletion process, click on No, go back

To delete a multiple user, from the User management page:

• Click on the bulk actions button

• Check/select the users to delete

• Click on the delete button or icon

A pop up box will appear, prompting you to confirm whether you would like to delete your users

• Click on Yes, delete to delete your user

• If you’d like to cancel the user deletion process, click on No, go back

Categories are a way of grouping your posts based on their content within a Survey. The setup in this guide is demonstrated in the below video as well. You can watch and follow the guide at the same time!

Video setup guide

Setup Guide

To access the Categories configuration page, on the sidebar, click on Settings

Then, click on Categories. You’ll be redirected to a page where you can manage categories on your deployment.

3.5.1 Adding and Configuring Categories

Unlike previous Ushahidi platform, your deployment DOES NOT come with pre installed/set-up categories. You will need to create this on your new Ushahidi deployment. Categories are now treated as custom fields within a Survey. This gives you the flexibility to add certain categories to some surveys, but not others.

There are two ways to create new categories.

First way to create categories: Navigate to Settings → Categories. Click on the Add Category button as shown below.

Add the following details to the form

• Category Name: Give your category a name that will appear on your homepage and when users are creating new posts.

• Description: You can provide a brief description of what kind of information you will fall under this category

• Child / parent settings: You can choose to set any category as a “child” to another, creating a hierarchy within the categories themselves, and will reflect this in their positioning on the sidebar.

• Default language: Click on the drop down menu to select your preferred default language

• Roles: You can opt to set your category as visible to specific user roles on your deployment here. This list is populated based on custom roles created. More on Roles here.

In the upper right corner of the category page, you will see the default language that your deployment is currently in.

You can translate the category into other languages. To do that:

• Click on Add translation at the upper right-hand corner of category form.

• A pop-up module will appear on your screen, check/select the language(s) you want to translate to.

• Click on Add to finish.

You will be redirected to a page with the translatable content in the default language and fields where you can add your translations.

Next:

• On the empty fields, translate the category name and description details into the chosen language e.g in the above image the default language is English and the added language is Spanish.

• Click Save when all is done to create the category. You can now choose to add this category to any of your Surveys.

• In the dropdown (inside the form), you will see the available languages the category has been translated into.

Second way to create categories: Add categories as custom fields as you build and edit Surveys. First, navigate to Settings → Surveys, and either select the already existing Survey you’d like to edit, or create a new Survey.

Click on Add field button in the survey builder/form and select Categories from the list of field options.

Configure the following

• Name: Name or prompt for your category survey field

• Field description: Optional description for the category

• Which labels should be available: Select which categories you’d like to add to the field as options

Click save to save your new categories field. It will now appear as a custom field with the appropriate categories on your Survey form.

3.5.2 Editing Categories

To edit a category, click on the desired category from the category list page.

You’ll get redirected to the Edit Category page, where you should be able to add/edit details as described in the adding categories section above.

When done, click on Save, and your changes will reflect shortly.

3.5.3 Deleting Categories

You can delete one or multiple categories at a time.

To delete a single category:

• Click on the category as if you want to edit the category

• Find the delete button at the bottom of the form

A pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete the category/categories.

• Click on Yes, delete to delete your category/categories

• If you’d like to cancel the category deletion process, click on No, go back

To delete multiple categories:

• Click on bulk actions from the Categories list page in settings

• Then click on the Delete button or icon

A pop up box will appear on the top of the page, prompting you to confirm whether you would like to delete the category/categories.

• Click on Yes, delete to delete your category/categories

• If you’d like to cancel the category deletion process, click on No, go back

Description

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. 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. "Member" role can be edited to update the permissions. "Admin" role cannot be edited to update the permissions.

Also, permissions are fully determined by Role-Based Access Control (RBAC). This means that each user can be assigned a specific role by an admin, which in turn grants them a particular set of operations within the platform. Below is a list of permissions included in the Mzima Platform;

Permissions included in the platform

• Manage Users: This permission entails the following operations;

  • Viewing the list of users on the platform

  • Adding, Editing or Deleting Users

  • Changing the Roles of Users

• Manage Posts: This permission entails the following;

  • Viewing the Posts

  • Adding or Editing their Posts

  • Publishing Posts

  • Archiving Posts

  • Adding Posts to Collections

• Manage Settings: This permission entails managing the settings in the platform

  • Users can manage the general settings which allow the user to:

    • Change the deployment details

    • Adjust the privacy settings for the deployment

    • Adjusting the location settings. You can find more about this here.

  • Adding, Editing or Deleting data sources

  • Adding, Editing or Deleting Surveys

  • Adding, Editing or Deleting Categories

  • Users can configure the HDX API and create webhooks

• Bulk Data Import and Export: Allows users to import and export CSV files

• Edit their own posts: Allows the user to be able to edit their posts

• Manage Collections and Saved Searches: This permission entails the following:

  • Addition/Removal of posts from all saved searches and collections

  • Editing all saved searches or collections

  • Deleting all saved searches and collections

• Delete Posts: This permission allows the user to be able to delete posts from the platform

• Delete their own Posts: This permission allows the user to be able to delete the posts that they have created themselves.

The setup in this guide is demonstrated in the below video as well. You can watch and follow the guide at the same time!

Video setup guide

Actions that need Authorization or Login to be Accessed

Users can still interact with the Mzima Platform while logged out, but their capabilities will be limited compared to those of logged-in users. Here is a breakdown:

If a user is not authenticated;

• The user can create posts on the platform although the usernames will be marked as Anonymous. Also, the user cannot edit their posts once submitted.

• The user can view statuses that are published only.

• The user can view saved filters if only the visibility of the filters is set to ‘Everyone’.

• The user can view categories if only the visibility of the categories is set to ‘Everyone’.

• The user can view collections if only the visibility of the collections is set to ‘Everyone’.

• The user can share posts.

If a user is authenticated;

• The user can access the platform settings if they have the 'Manage Settings' permission only.

• The user can create saved filters and adjust the visibility.

• The users can create posts. It is worth noting that they can only edit them if they have the 'Edit their own posts' permission.

• The user can create a collection but they will only be visible to them and the admins. If they have the ‘Manage Collections and Saved Searches’ permission in their role, they can adjust the visibility to either ‘only me’, ‘everyone’ or ‘specific roles’. Also, a user can create and delete collections but cannot edit them if they do not have this permission.

• The user can see published posts for everyone and their posts that are 'under review' or 'archived'.

Setup Guide

To access the roles management page, on the sidebar, click on Settings

Then, click on Roles

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

4.1.1 Add Role

To add a custom user role, click on the yellow Add icon

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. The list below shows the list of permissions included in the platform. You can view the brief breakdown of each of the permissions that can be granted to users by selecting here.

  • Manage Users:

  • Manage Posts:

  • Manage Settings:

  • Bulk Data import and Export:

  • Edit their own posts:

  • Manage collections and saved searches:

• Click on Save.

4.1.2 Edit Role

To edit a role, click on a role from the list provided to you.

Next:

• 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.

4.1.3 Delete Role

To delete a role, click on a role from the Roles management list page

Then, click on the Delete button at the bottom of the page

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

This section allows you to configure Twitter as a data source, and subsequently pull unstructured posts from specific Twitter hashtags.

For you to be able to pull tweets based on hashtags, you will need to set up your Ushahidi deployment as an application on Twitter. To get started,

• Click on the drop-down icon on the right as shown

• Click on Create a new Twitter application. This will redirect you to https://developer.twitter.com/en

• Sign into https://developer.twitter.com/en using your Twitter username and password.

• Click on the Developer Portal to take you to the page where you will create your app or visit https://developer.twitter.com/en/portal/dashboard

• Once you select the Developer Portal, you will be directed to your portal immediately. If you haven't created a developer's profile yet, you will be redirected to sign up for one as shown in the picture below:

• From here, you can choose either to Sign up for Free Account or choose one of the paid tiers to subscribe to. Note that the free tier limits the feature sets offered in these other paid tiers. Check their website for more information: https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api

• Once you select the option Sign up for Free Account, you will need to describe your use cases and also agree to the terms and conditions stipulated.

• Once you have filled in your description and checked all the boxes, click Submit.

• Once you click Submit, your developer account will automatically be created and you will be redirected to the Developer's Portal. Here, you will find out that Twitter/X has already created a project for you together with the app. You can proceed with this one, or you can delete the pre-made project and create yours afresh. If you decide to delete it, you can create a new one as shown below.

• Once selected, you should give your project a name

• Afterwards, select your use case for how you intend to use the platform

• Provide a brief description of your project

• Once you are done, you should click Next to set up your app.

To set up your app in this project, follow the steps below;

• Select your App name.

You can enter the name of your deployment to make it more memorable.

• Click on Next to generate your keys and token.

• Here, you will see the API Key, API Key Secret, and the Bearer Token generated for your app. Make sure to master or note down these codes safely since you will use them when filling out the form in the Ushahidi Platform. These codes can be generated later on as we will see in the process down below. Keep in mind that regenerating these keys might need you to update your code for your app to work properly.

Note: The API Key and Secret Key are treated like passwords, therefore they should be memorized or saved in a secure location. If the security has been compromised/you forgot to save the keys, new ones can be generated.

Test application configuration on Twitter.

• Go to Overview https://developer.twitter.com/en/portal/projects-and-apps, adjacent to your project app name, there is a Key icon, click on it to view your API and Access token keys. These will be needed to configure Twitter/X with your deployment.

• You’ll get redirected to a page where you can grab details needed to configure your Ushahidi deployment i.e CONSUMER KEY, CONSUMER SECRET, ACCESS TOKEN, ACCESS TOKEN SECRET.

• Go back to your Twitter configuration page on your deployment and fill in all the details from your Twitter app management page.

• On your Twitter developer account panel, click on Reveal API Key hint next to API key and Secret to display a hint of your API Key. If you had not captured these codes before, you will be required to generate new ones. Copy and paste them on your deployment API and secret fields.

• On the same panel, you will see Access Token and Secret. You’ll have to generate an ACCESS TOKEN and ACCESS TOKEN SECRET by clicking on the Generate button.

• Copy and paste them on your deployment ACCESS TOKEN and ACCESS TOKEN SECRET fields.

NB: if you save them without copying and pasting, you will be regenerating new ones.

• Add the hashtags you want to pull tweets from in the Twitter Search Terms section. You can choose more than one hashtag, separated by a comma. It is recommended that short and clear hashtags be chosen.

• Click on Save and this data source’s settings will be saved. Unstructured posts from Twitter will now get pulled into the platform.

Configure Twitter in the Ushahidi Platform

• To enable/disable the Twitter data source, simply click on the green toggle.

• If you’d like to edit your Twitter configuration, click on the Twitter option and make your changes. Once you are done click Save. You can also delete Twitter as a data source by selecting the delete button.

You can also choose which survey you want to import the data source into and you can toggle the option of accepting survey submissions from this source.

It will only take a few minutes and the tweets will appear on your deployment.

The map view displays posts on a map - particularly posts that have location information.

Posts and the map area of the map view:

• Each post appears as an icon (i.e. a marker/pointer) on the map. In the event that you opted to combine nearby posts on your Map settings page ( of this manual), 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.

Sidebar and Toolbar: See the page below for some more map view related information when it comes to managing data on your deployment through the sidebar and toolbar.

The Ushahidi platform provides you with modes (i.e. views) 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.

Guest/anonymous users or viewers of a deployment can access three modes as shown below:

• Map view

• Data view

• Activity view

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

• Map view

• Data view

• Activity view

• Settings view

Your Ushahidi 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.

The Activity view gives you a summary of how people are interacting with your deployment over time.

Compare activity over time: You can filter post count in a line chart over time for a particular range, and for:

• All posts in the deployment

• Categories that the posts belong to

• Surveys that the posts were submitted to

• Status i.e. whether they’re published or not

Compare activity by Volume: You can filter post count in a bar chart by volume for a particular range, and for:

• Categories that the posts belong to

• Surveys that the posts were submitted to

• Status i.e whether they’re published or not

Sidebar and Toolbar: See the page below for some more activity view related information when it comes to managing data on your deployment through the sidebar and toolbar.

Note: Some data displayed on this page may or may not be available to all users viewing the data view. What you can see or the actions you can perform is dependent on the permissions you have or are granted as a user.

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.

Posts details/edit and the data view:

• View individual post details

• Edit posts to either change existing structures or assign posts from incoming datasources to a survey

Managing posts from the data view:

• Add posts to collections

• Publish posts

• Put posts under review

• Archive posts

• Share posts

• Delete posts

Bulk actions for posts from the data view: Perform bulk actions( publishing, putting under review, archiving, adding to collections and deleting) on multiple posts at a time.

Sidebar and Toolbar: See the page below for some more data view related information when it comes to managing data on your deployment through the sidebar and toolbar.

You will find more detailed information about managing data on your deployment in Section 6. But here is a quick run-through about managing data on your deployment through the sidebar and toolbar in any of the views mentioned earlier: Map view, Data view, Activity View and Settings View.

Add new post: Add new posts from the sidebar as shown in the screenshot below.

Sources: From the toolbar, Get a breakdown of incoming posts by source (when in map view or data view).

Languages: From the toolbar, visitors to your Ushahidi instance can select the language they'd like to interact with your data in. The language list consists of languages that have been translated.

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. Ushahidi allows for collection of posts via

• SMS: These can be configured to come in via SMSSync, FrontlineSMS, Nexmo and Twilio.

• Twitter: You can pull our tweets based on specific hashtags, search terms, and/or directly from specific accounts.

• Email: You can configure your deployment to receive post from an email address

NB: You can configure SMS, Twitter and Email as data sources as described in of this manual

• Web(your deployment page online): Since Ushahidi is responsive, you can add a post from the web app from any device that can access the internet (a computer, tablet, or mobile phone).

• Smartphone apps: Our native applications on Android and iOS are still a work in progress at the moment.

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

In the below video setup guide you will find how to view, filter, edit, publish, delete, export, and how to share your posts.

Video Setup Guide

Written Setup Guides

6.3.1 Directly from the Web

Registered/non registered users can create posts using the same process described below. For descriptive purposes, the post below has one tasks.

Video setup on how to add/submit posts

To create a post:

• Click on the yellow Add new post button from the sidebar as shown below on your homepage.

• 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.

To create a post (continued):

• At the top right corner of the create survey form, 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.

6.3.2 Email

If email has been configured and enabled as a data source on your deployment, users will be able to send in posts directly by sending an email to the email address configured. These will appear in your data mode view, and available via the search filter. See chapter 3.4 for more configuration details

6.3.3 Twitter

If Twitter has been configured and enabled as a data source on your deployment, you will be able to pull in tweets corresponding to the hashtags you have indicated. These will appear in your data mode view, and available via the search filter. See chapter 3.4 for more configuration details

6.3.4 SMS

If SMS has been configured and enabled as a data source on your deployment, users will be able to send in text messages directly to a configured short code or sms number of your choice, which will be pulled in to your data view and available via the search filter. See chapter 3.4 for more configuration details

6.3.5 Smartphone apps

(Note: Mzima Mobile app is still in development) Users should be able to download the Ushahidi Mobile app for Android or iOS, search for your deployment, or add the URL directly. Once synced, they should be able to add posts directly onto your deployment in a similar manner to the web app.

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.

On this page, you will find information about how to translate posts into other available languages.

The post translation function is only available to admins or registered users with adequate permissions. This means that non registered users cannot translate posts. To translate a post:

Select a post from your data view.

Click on the edit icon on the post cards or post details. This will load the post editor form on the right pane of your page, where you’ll be able to edit any of the content.

Select language to translate post to:

• In the upper right corner of the post editor form, you will see a dropdown with the default language that your deployment is currently in.

• Click on the dropdown to select another language, notice the change of language on the text/body of the post editor form.

• Click save/submit once your edit is done.

Note: The languages that will be available on the drop down list will be the ones you selected while translating your survey

• You will be redirected to a page with the translatable content in the default language and fields where you can add your translations.

• On the empty fields, translate the fields’ content into the chosen language e.g in the above image the default language is English and the added language is French.

• Click Save at the upper or bottom right hand side of the screen when all is done.

• To see translations, at the upper left corner of the page, click on the dropdown menu and see the available languages that the postcard can be viewed in, click on the language you prefer to view in.

(From our example above we translated ours to Spanish)

Filters can be applied to narrow down a large amount of data. You can filter posts by many types of parameters, for example: Surveys, Sources, Categories, Status, Date Ranges, and Location.

Surveys and Sources filters are located on the left side of the toolbar, while other filters are located towards the top of the toolbar.

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

Find the button to sort posts just before all the post cards or the post details in the data view. You can sort posts by:

• Date of creation

• Post date i.e date when it was assigned to a survey

• Date updated

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). We'll cover the structuring process in section 6.4.1 below.

To edit a post:

• Select a post from your data view

• Click on the Edit Icon. 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.

6.4.1 Structuring posts

6.4.2 Locked posts

Note: Some data displayed on this page may or may not be available to all users viewing the data view. What you can see or the actions you can perform is dependent on the permissions you have or are granted as a user.

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 elements or perform certain actions as shown in the sections below.

See 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 Web, SMS, Email or Twitter?):

• Structured posts i.e. posts coming from web/smartphones will have the web label on them.

• Unstructured posts i.e. posts coming from sms, email etc. will have a label denoting their respective sources e.g. sms, email etc

See 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 survey type, location and the categories.

If you’re an admin/your user role permits, you’ll should also be able to see the Edit button/icon on the post card and post details of the selected post.

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)

The platform now allows for data export, enabling you to download posts from the platform in CSV format. You can download posts via the export and tag data feature.

The setup in this guide is demonstrated in the video below as well. You can watch and follow the guide at the same time!

Video setup guide

Steps to exporting a CSV file

To export a CSV file,

• Click on settings and select Export and tag data

• Once there, click on the Export all data button within the same section.

• You can also select the specific fields from each survey you want to export if you don't want to export all data at once. Once you have selected your fields, select Export Selected Fields

• A small confirmation box will appear seeking confirmation on whether you would like to proceed with exporting your data.

  • Click on Got it to export your CSV file

  • Click on Cancel export if you would like to terminate the export process.

• You should get a CSV file named after your deployment name in your downloads folder

Ushahidi's platform allows you to export your data as a CSV file or assign tags and attributes to your data and upload directly to a Humanitarian Data Exchange (HDX) account or export as a tagged CSV file.

In this section, you will learn how to:

1. Export all of your data from Ushahidi as a CSV, choose specific survey fields you want to export as a CSV

2. Assign , and choose to upload to an account or download as a HXL 'tagged' CSV file.

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

The Data Import feature allows you to import posts into the platform. It is particularly useful in cases where:-

• You need to upload posts in bulk

• You need to upload posts that people can’t send to you via email/phone but have the data available in CSV format

• (In future) You are transferring data from one platform to another

To import a CSV file,

First, you need to have prepared your CSV file. Make sure that

• You are uploading a file in CSV format. Any other file formats are not accepted

• Your CSV file size does not exceed 2MB

• Your CSV file has Column headers( these will be useful when mapping your CSV column to the survey fields)

• Geographic location information is separated into two columns; one for Latitude, and the other for Longitude.