New setting batch save endpoint payload sample

[dubdabasoduba]

Payload one.

{
  "settingConfigurations": [
    {
      "settings": [
                {
          "description": "The proportion of Hepatitis B surface antigen (HBsAg) seroprevalance in the general population is 2% or higher.",
          "label": "Hep B prevalence is intermediate (2% or higher) or high (5% or higher)",
          "value": "true",
          "key": "pop_hepb",
          "locationId":"<uuid> the location the setting is being adapted for",
          "uuid":"<uuid> only required if its an update to a location adaptation that was made earlier",
          "type":"boolean"
        },
        {
          "description": "There is a national Hepatitis B ANC routine screening program in place.",
          "label": "National Hep B ANC routine screening program established",
          "value": "true",
          "key": "pop_hepb_screening",
          "locationId":"<uuid> the location the setting is being adapted for",
          "uuid":"<uuid> only required if its an update to a location adaptation that was made earlier",
          "type":"boolean"
        },
        {
          "description": "The proportion of Hepatitis C virus (HCV) antibody seroprevalence in the general population is 2% or higher. ",
          "label": "Hep C prevalence is intermediate (2% or higher) or high (5% or higher)",
          "value": "false",
          "key": "pop_hepc",
          "locationId":"<uuid> the location the setting is being adapted for",
          "uuid":"<uuid> only required if its an update to a location adaptation that was made earlier",
          "type":"boolean"
        }
      ],
      "identifier": "population_characteristics",
      "type": "SettingConfiguration",
      "teamId":"<uuid> only required if the settings are tied to a team",
      "team":"<team name> only required if the settings are tied to a team",
      "providerId":"<uuid> only required is the settings are tied to a provider"
    }
  ]
}

Payload two

[
  {
    "settingConfigurations": [
      {
        "settings": [
          {
            "description": "The proportion of Hepatitis B surface antigen (HBsAg) seroprevalance in the general population is 2% or higher.",
            "label": "Hep B prevalence is intermediate (2% or higher) or high (5% or higher)",
            "value": "true",
            "key": "pop_hepb",
            "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
            "type": "boolean"
          },
          {
            "description": "There is a national Hepatitis B ANC routine screening program in place.",
            "label": "National Hep B ANC routine screening program established",
            "value": "true",
            "key": "pop_hepb_screening",
            "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
            "type": "boolean"
          },
          {
            "description": "The proportion of Hepatitis C virus (HCV) antibody seroprevalence in the general population is 2% or higher. ",
            "label": "Hep C prevalence is intermediate (2% or higher) or high (5% or higher)",
            "value": "false",
            "key": "pop_hepc",
            "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
            "type": "boolean"
          }
        ],
        "identifier": "population_characteristics",
        "type": "SettingConfiguration",
        "team_id": "<uuid> only required if the settings are tied to a team",
        "team": "<team name> only required if the settings are tied to a team",
        "provider_id": "<uuid> only required is the settings are tied to a provider",
        "locationId": "<uuid> the location the setting is being adapted for"
      }
    ]
  },
  {
    "settingConfigurations": [
      {
        "settings": [
          {
            "description": "The proportion of Hepatitis B surface antigen (HBsAg) seroprevalance in the general population is 2% or higher.",
            "label": "Hep B prevalence is intermediate (2% or higher) or high (5% or higher)",
            "value": "true",
            "key": "pop_hepb",
            "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
            "type": "boolean"
          },
          {
            "description": "There is a national Hepatitis B ANC routine screening program in place.",
            "label": "National Hep B ANC routine screening program established",
            "value": "true",
            "key": "pop_hepb_screening",
            "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
            "type": "boolean"
          },
          {
            "description": "The proportion of Hepatitis C virus (HCV) antibody seroprevalence in the general population is 2% or higher. ",
            "label": "Hep C prevalence is intermediate (2% or higher) or high (5% or higher)",
            "value": "false",
            "key": "pop_hepc",
            "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
            "type": "boolean"
          }
        ],
        "identifier": "population_characteristics",
        "type": "SettingConfiguration",
        "teamId": "<uuid> only required if the settings are tied to a team",
        "team": "<team name> only required if the settings are tied to a team",
        "providerId": "<uuid> only required is the settings are tied to a provider",
        "locationId": "<uuid> the location the setting is being adapted for"
      }
    ]
  }
]

[githengi]

@dubdabasoduba I would go with the below

 [
    {
      "settings": [
                {
          "description": "The proportion of Hepatitis B surface antigen (HBsAg) seroprevalance in the general population is 2% or higher.",
          "label": "Hep B prevalence is intermediate (2% or higher) or high (5% or higher)",
          "value": "true",
          "key": "pop_hepb",
          "locationId":"<uuid> the location the setting is being adapted for",
          "uuid":"<uuid> only required if its an update to a location adaptation that was made earlier"
        },
        {
          "description": "There is a national Hepatitis B ANC routine screening program in place.",
          "label": "National Hep B ANC routine screening program established",
          "value": "true",
          "key": "pop_hepb_screening",
          "locationId":"<uuid> the location the setting is being adapted for",
          "uuid":"<uuid> only required if its an update to a location adaptation that was made earlier"
        },
        {
          "description": "The proportion of Hepatitis C virus (HCV) antibody seroprevalence in the general population is 2% or higher. ",
          "label": "Hep C prevalence is intermediate (2% or higher) or high (5% or higher)",
          "value": "false",
          "key": "pop_hepc",
          "locationId":"<uuid> the location the setting is being adapted for",
          "uuid":"<uuid> only required if its an update to a location adaptation that was made earlier"
        }
      ],
      "identifier": "population_characteristics",
      "type": "SettingConfiguration",
      "teamId":"<uuid> only required if the settings are tied to a team",
      "team":"<team name> only required if the settings are tied to a team",
      "providerId":"<uuid> only required is the settings are tied to a provider"
    }
  ]

[vincent-karuri]

I think the converstation was around removing the enclosing settingConfigurations and simply have an array settings.

[moshthepitt]

@dubdabasoduba @vincent-karuri some questions:

1. Could you describe when you use payload 1 Vs payload 2?
2. Its not clear to me when one needs to include uuid i.e. "only required if its an update to a location adaptation that was made earlier" --> what does this mean from the frontend engineers point of view?
3. What exactly does uuid refer to anyway? Where does the web client get it?
4. Is it required to provide both team_id and team if the settings are tied to a team? Why? Where does the web client get team information?
5. What is a provider_id? Where does the web client get it?
6. Concerning locationId can you confirm if we are dealing with Reveal-style jurisdictions or not? Where does the web client get these values?
7. Is value always always ALWAYS a boolean?
8. key -> please confirm if is this expected to be typed in by the user
9. Is it correct to say that the user will type in both description and label?
10. "identifier": "population_characteristics"- is this expected to always be exactly this way? If not, could you describe how to deal with this field?
11. "type": "SettingConfiguration" - is this expected to always be exactly this way? If not, could you describe how to deal with this field?

[dubdabasoduba]

I think the converstation was around removing the enclosing settingConfigurations and simply have an array settings. @vincent-karuri

"identifier": "population_characteristics",
"type": "SettingConfiguration",
"team_id":"<uuid> only required if the settings are tied to a team",
"team":"<team name> only required if the settings are tied to a team",
"provider_id":"<uuid> only required is the settings are tied to a provider"

this attributes will not change for the period a user is logged into adapt the settings hence my reason of having them on the root of the payload.

[dubdabasoduba]

@moshthepitt

1. Could you describe when you use payload 1 Vs payload 2? --> We are trying to decide which between the two payloads we should use.
2. Its not clear to me when one needs to include uuid i.e. "only required if its an update to a location adaptation that was made earlier" --> what does this mean from the frontend engineers point of view? -- This piece on the scope document describes how the settings will be saved in the database. the uuid is a unique identifier to a specific setting. @githengi @vincent-karuri @ndegwamartin I think we might need to update the the settings GET API endpoint to also return the settings uuid
3. What exactly does uuid refer to anyway? Where does the web client get it? --> The GET API endpoint should come with it. It is a unique identifier for each setting.
4. Is it required to provide both team_id and team if the settings are tied to a team? Why? Where does the web client get team information? --> I am not sure its required to have both I check and update you later. On login in OpenSRP these /opensrp/security/authenticate returns a payload that has a couple of things. the team_id & team are found in the team > team object. The teamId == uuid & team == teamName. A sample payload is attached here
5. What is a provider_id? Where does the web client get it? --> this is the logged user username am I right @githengi. This can also be found in the payload shared above on the user
6. Concerning locationId can you confirm if we are dealing with Reveal-style jurisdictions or not? Where does the web client get these values? -- I assume you mean locations with Geo-jsons if so, no this are the location ids from OpenMRS for instances using OpenMRS. I am not sure how the locations look like for instances not using OpenMRS. The locationId is just a UUID. The location hierarchy endpoint /opensrp/location/location-tree will always return a location and its uuid.
7. Is value always always ALWAYS a boolean? -- nope this can be a boolean,number, string
8. key -> please confirm if is this expected to be typed in by the user --> yes
9. Is it correct to say that the user will type in both description and label? --> yes
10. "identifier": "population_characteristics"- is this expected to always be exactly this way? If not, could you describe how to deal with this field? -- in the case of population characteristics yes it will also remain same but different settings will have different identifiers.
11. "type": "SettingConfiguration" - is this expected to always be exactly this way? If not, could you describe how to deal with this field? -- I would say it would remain the same. @githengi @ndegwamartin do we have a different type of settings?

[moshthepitt]

@dubdabasoduba thank you.

Its not clear to me when one needs to include uuid i.e. "only required if its an update to a location adaptation that was made earlier" --> what does this mean from the frontend engineers point of view? -- This piece on the scope document describes how the settings will be saved in the database. the uuid is a unique identifier to a specific setting. @githengi @vincent-karuri @ndegwamartin I think we might need to update the the settings GET API endpoint to also return the settings uuid

• When creating new settings, I assume that this should be blank?
• I suppose there is no harm in always providing this for existing settings?

Is value always always ALWAYS a boolean? -- nope this can be a boolean,number, string

How should the web client identify what kind of value a particular setting should accept?

Concerning locationId can you confirm if we are dealing with Reveal-style jurisdictions or not? Where does the web client get these values? -- I assume you mean locations with Geo-jsons if so, no this are the location ids from OpenMRS for instances using OpenMRS. I am not sure how the locations look like for instances not using OpenMRS. The locationId is just a UUID. The location hierarchy endpoint /opensrp/location/location-tree will always return a location and its uuid.

@githengi will a similar (or the same) API endpoint be available for when we completely switch over to jurisdictions?

---

When setting "global" settings, what value of locationId should the web UI provide? I assume that this is the root parent location in the hierarchy?

[dubdabasoduba]

@dubdabasoduba I would go with the below

 [
    {
      "settings": [
                {
          "description": "The proportion of Hepatitis B surface antigen (HBsAg) seroprevalance in the general population is 2% or higher.",
          "label": "Hep B prevalence is intermediate (2% or higher) or high (5% or higher)",
          "value": "true",
          "key": "pop_hepb",
          "locationId":"<uuid> the location the setting is being adapted for",
          "uuid":"<uuid> only required if its an update to a location adaptation that was made earlier"
        },
        {
          "description": "There is a national Hepatitis B ANC routine screening program in place.",
          "label": "National Hep B ANC routine screening program established",
          "value": "true",
          "key": "pop_hepb_screening",
          "locationId":"<uuid> the location the setting is being adapted for",
          "uuid":"<uuid> only required if its an update to a location adaptation that was made earlier"
        },
        {
          "description": "The proportion of Hepatitis C virus (HCV) antibody seroprevalence in the general population is 2% or higher. ",
          "label": "Hep C prevalence is intermediate (2% or higher) or high (5% or higher)",
          "value": "false",
          "key": "pop_hepc",
          "locationId":"<uuid> the location the setting is being adapted for",
          "uuid":"<uuid> only required if its an update to a location adaptation that was made earlier"
        }
      ],
      "identifier": "population_characteristics",
      "type": "SettingConfiguration",
      "teamId":"<uuid> only required if the settings are tied to a team",
      "team":"<team name> only required if the settings are tied to a team",
      "providerId":"<uuid> only required is the settings are tied to a provider"
    }
  ]

@ndegwamartin @vincent-karuri what do you think?

[dubdabasoduba]

@moshthepitt

• When creating new settings, I assume that this should be blank? --> Yes

• I suppose there is no harm in always providing this for existing settings? --> yes

• How should the web client identify what kind of value a particular setting should accept? --> For existing settings the returned setting will have a type attribute that will tell you the kind of value it should be. I have updated the GET endpoint response to include it. @githengi , @ndegwamartin & @vincent-karuri we also need to update this GET endpoint to return the setting_type as type. For new settings then we need a dropdown for the users to choose the type from. The list of expected types will be found here

• When setting "global" settings, what value of locationId should the web UI provide? I assume that this is the root parent location in the hierarchy? --> We could leave it as blank but for safety reasons we can use the root parent location.

[moshthepitt]

For new settings then we need a dropdown for the users to choose the type from. The list of expected types will be found here

Note to self

setting_type values:

• Boolean
• String
• number

---

@dubdabasoduba does the payload here need to have setting_type in it?

[dubdabasoduba]

@moshthepitt does the payload here need to have setting_type in it? --> Yes, it will

[moshthepitt]

Is it required to provide both team_id and team if the settings are tied to a team? Why? Where does the web client get team information? --> I am not sure its required to have both I check and update you later. On login in OpenSRP these /opensrp/security/authenticate returns a payload that has a couple of things. the team_id & team are found in the team > team object. The teamId == uuid & team == teamName. A sample payload is attached here

@dubdabasoduba did you check on this?

[vincent-karuri]

[
  {
    "settings": [
      {
        "description": "The proportion of Hepatitis B surface antigen (HBsAg) seroprevalance in the general population is 2% or higher.",
        "label": "Hep B prevalence is intermediate (2% or higher) or high (5% or higher)",
        "value": "true",
        "key": "pop_hepb",
        "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
        "type": "boolean"
      },
      {
        "description": "There is a national Hepatitis B ANC routine screening program in place.",
        "label": "National Hep B ANC routine screening program established",
        "value": "true",
        "key": "pop_hepb_screening",
        "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
        "type": "boolean"
      },
      {
        "description": "The proportion of Hepatitis C virus (HCV) antibody seroprevalence in the general population is 2% or higher. ",
        "label": "Hep C prevalence is intermediate (2% or higher) or high (5% or higher)",
        "value": "false",
        "key": "pop_hepc",
        "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
        "type": "boolean"
      }
    ],
    "identifier": "population_characteristics",
    "type": "SettingConfiguration",
    "team_id": "<uuid> only required if the settings are tied to a team",
    "team": "<team name> only required if the settings are tied to a team",
    "provider_id": "<uuid> only required is the settings are tied to a provider",
    "locationId": "<uuid> the location the setting is being adapted for"
  },
  {
    "settings": [
      {
        "description": "The proportion of Hepatitis B surface antigen (HBsAg) seroprevalance in the general population is 2% or higher.",
        "label": "Hep B prevalence is intermediate (2% or higher) or high (5% or higher)",
        "value": "true",
        "key": "pop_hepb",
        "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
        "type": "boolean"
      },
      {
        "description": "There is a national Hepatitis B ANC routine screening program in place.",
        "label": "National Hep B ANC routine screening program established",
        "value": "true",
        "key": "pop_hepb_screening",
        "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
        "type": "boolean"
      },
      {
        "description": "The proportion of Hepatitis C virus (HCV) antibody seroprevalence in the general population is 2% or higher. ",
        "label": "Hep C prevalence is intermediate (2% or higher) or high (5% or higher)",
        "value": "false",
        "key": "pop_hepc",
        "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
        "type": "boolean"
      }
    ],
    "identifier": "population_characteristics",
    "type": "SettingConfiguration",
    "teamId": "<uuid> only required if the settings are tied to a team",
    "team": "<team name> only required if the settings are tied to a team",
    "providerId": "<uuid> only required is the settings are tied to a provider",
    "locationId": "<uuid> the location the setting is being adapted for"
  }
]

@dubdabasoduba this is my understanding of what the payload would look like, an array of settings by location

OR employing your suggestion to share some fields:

{
  "settings": [
    {
      "description": "The proportion of Hepatitis B surface antigen (HBsAg) seroprevalance in the general population is 2% or higher.",
      "label": "Hep B prevalence is intermediate (2% or higher) or high (5% or higher)",
      "value": "true",
      "key": "pop_hepb",
      "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
      "type": "boolean",
      "identifier": "population_characteristics",
      "locationId": "<uuid> the location the setting is being adapted for"
    },
    {
      "description": "There is a national Hepatitis B ANC routine screening program in place.",
      "label": "National Hep B ANC routine screening program established",
      "value": "true",
      "key": "pop_hepb_screening",
      "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
      "type": "boolean",
      "identifier": "population_characteristics",
      "locationId": "<uuid> the location the setting is being adapted for"
    },
    {
      "description": "The proportion of Hepatitis C virus (HCV) antibody seroprevalence in the general population is 2% or higher. ",
      "label": "Hep C prevalence is intermediate (2% or higher) or high (5% or higher)",
      "value": "false",
      "key": "pop_hepc",
      "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
      "type": "boolean",
      "identifier": "population_characteristics",
      "locationId": "<uuid> the location the setting is being adapted for"
    },
    {
      "description": "The proportion of Hepatitis B surface antigen (HBsAg) seroprevalance in the general population is 2% or higher.",
      "label": "Hep B prevalence is intermediate (2% or higher) or high (5% or higher)",
      "value": "true",
      "key": "pop_hepb",
      "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
      "type": "boolean",
      "identifier": "population_characteristics",
      "locationId": "<uuid> the location the setting is being adapted for"
    },
    {
      "description": "There is a national Hepatitis B ANC routine screening program in place.",
      "label": "National Hep B ANC routine screening program established",
      "value": "true",
      "key": "pop_hepb_screening",
      "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
      "type": "boolean",
      "identifier": "population_characteristics",
      "locationId": "<uuid> the location the setting is being adapted for"
    },
    {
      "description": "The proportion of Hepatitis C virus (HCV) antibody seroprevalence in the general population is 2% or higher. ",
      "label": "Hep C prevalence is intermediate (2% or higher) or high (5% or higher)",
      "value": "false",
      "key": "pop_hepc",
      "uuid": "<uuid> only required if its an update to a location adaptation that was made earlier",
      "type": "boolean",
      "identifier": "population_characteristics",
      "locationId": "<uuid> the location the setting is being adapted for"
    }
  ],
  "type": "SettingConfiguration",
  "teamId": "<uuid> only required if the settings are tied to a team",
  "team": "<team name> only required if the settings are tied to a team",
  "providerId": "<uuid> only required is the settings are tied to a provider"
}

I moved the identifier field to each setting to allow batch insert of settings of different types.

[vincent-karuri]

When setting "global" settings, what value of locationId should the web UI provide? I assume that this is the root parent location in the hierarchy? --> We could leave it as blank but for safety reasons we can use the root parent location.

This should be the root parent location.

[moshthepitt]

@vincent-karuri could you include setting_type here https://github.com/OpenSRP/opensrp-server-web/issues/267#issuecomment-607133977?

[vincent-karuri]

@dubdabasoduba shouldn't all settings be strings (regardless of the underlying data type).

The implication here would be that the admin would know how to distinguish between data types otherwise?

cc @moshthepitt

[vincent-karuri]

On the other hand, without web client-side validation, we may end up with values that cause the Android client to crash when casting.

Ideas?

[moshthepitt]

@vincent-karuri I have seen that you have "type": "boolean" --> I think we can use this. And I presume that these values are valid for type:

• Boolean
• String
• number

Yes?

[vincent-karuri]

I modified this from what @dubdabasoduba had provided, so yes, it should be the same thing.

[githengi]

@moshthepitt the OpenMRS locations are different from reveal like locations. @dubdabasoduba It would be wise to support OpenSRP locations as OpenMRS will be decoupled in the next quarter.

[vincent-karuri]

Something I've noticed, and that @dubdabasoduba alluded to, with these data model changes, we would need a way of migrating existing server deployments.

Is this something we are ready to do?

If not, we would be forced to keep the current model and add fields as suggested here;

[githengi]

Migrations must be factored in as the database schema is being refactored. This should be part of database schema changes

[vincent-karuri]

Agreed but this will need to be communicated to everyone who currently uses the Settings API, in case they wish to use the web client in future.

So my question was whether this is agreeable? Are we all on-board that this is the path we wish to take?

[ndegwamartin]

@vincent-karuri are you referring to the path of migration in your question above?