Creating Diagram Definitions for Campaigns

Introduction

The Campaign module of SORMAS supports basic diagrams that can be displayed on the Campaign Dashboard and that are defined using the JSON format. As with campaign form definitions, there is currently no user interface to insert these diagrams into the database. Instead, the following script can be used to do so manually:

INSERT INTO campaigndiagramdefinition(id, uuid, changedate, creationdate, diagramid, diagramtype, diagramcaption)
	VALUES (nextval('entity_seq'), overlay(overlay(overlay(
		substring(upper(REPLACE(CAST(CAST(md5(CAST(random() AS text) || CAST(clock_timestamp() AS text)) AS uuid) AS text), '-', '')), 0, 30) 
		placing '-' from 7) placing '-' from 14) placing '-' from 21), now(), now(), '???', 'COLUMN', '???');

The column diagramid refers to the unique ID of the diagram in the database while diagramcaption is the actual caption that is displayed on the dashboard.

The actual diagram definition needs to be inserted into the campaigndiagramseries column. If the diagram should also support percentages, the campaignseriestotal column needs to be filled. If the percentage-based diagram should be the default (toggling between total values and percentages can be done via the options icon on every diagram), percentagedefault has to be set to true.

Diagram Series

A basic example of a diagram definition (campaigndiagramseries) would look like this:

[
  {"fieldId": "firstField", "formId": "exampleForm"},
  {"fieldId": "secondField", "formId": "exampleForm", "caption": "short caption"},
  {"fieldId": "thirdField", "formId": "exampleForm"}
]

This diagram would display three series, one for each defined fieldId. The fieldId needs to match the ID of one of the fields specified in the JSON definition of the campaign form referenced in formId. Furthermore, it is possible to specify an optional caption that will be used to provide a shorter name that is displayed in the chart.

In addition, it is possible to define stacks that individual series should belong to. The extended example would look like this:

[
  {"fieldId": "firstField", "formId": "exampleForm", "stack": "Stack 1"},
  {"fieldId": "secondField", "formId": "exampleForm", "stack": "Stack 2"},
  {"fieldId": "thirdField", "formId": "exampleForm", "stack": "Stack 3"}
]

The first two fields would now be shown in one stack, while the third field would be moved to a second stack. The name of the stack is also the text that is displayed in the diagram.

It is also possible to define specific colors for the series. The extended example would look like this:

The color should be defined as rgb using hexadecimal color codes (e.g. #FF0000 is red, see W3Schools.com ).

Percentage Diagrams

A basic example of the definition of a diagram showing percentages (campaignseriestotal) would look like this:

The fieldId specifies the field that the total value is taken from. This value then is used as the denominator for the calculation of the percentage value. The percentages are always calculcated based on the campaigndiagramseries definition. If we combine this example with the one from the section above, the diagram showing percentages would show three series again. However, it would not show total values, but the values of each of the fields defined above (firstField, secondField and thirdField) divided by the value in the referenceField specified in the campaignseriestotal column.

The definitions of percentage diagrams also support stacks. These have to match the stack names defined in the campaigndiagramseries column. The specified fieldId is then used as the denominator for all fields specified in campaigndiagramseries that belong to the same stack.

An alternative way of presenting percentage values is to use the number of existing forms instead of the value of a specific field as the denominator. This can be used together with fields of the "YesNo" type in order to show in how many of these forms the value "Yes" or "No" has been selected.

Take this campaigndiagramseries as an example:

This series shows the number of forms where the exampleField, which is of type "YesNo", has been set to "Yes" (specified by "true" in the referenceValue parameter).

The corresponding definition of the campaignseriestotal column would look like this:

As you can see, only a formId, no fieldId is needed in this case. With this definition, the percentage diagram will display in how many out of the total number of existing forms of this type the field defined above has been set to the reference value, also defined above.

Using population data

You can also rely on population data as reference value for percentage diagrams. In order for this to work you have to import population data for regions and districts into the system using the population view in the SORMAS configuration user interface.

Translations

Campaign diagrams can be translated to every language that is supported by SORMAS. To do this, JSON needs to be specified in the campaigndiagramtranslations column. A basic translation definition would look like this:

The languageCode attribute defines the locale the translation is for and needs to match one of the locales supported by SORMAS. The diagramCaption attribute is the translation of the diagram caption. The stackCaptions and seriesNames attributes expect a list of translations, each of which need to specify an elementId and a caption. For stackCaptions the elementId is the stack name, while for seriesNames is obtained by concatenating formId and fieldId, which are the ids of the form and of the translated field in the form. The translated caption supports basic HTML elements.