API Documentation for HortiView¶

API Definitions¶

The following API definitions are available for reference. Please make sure to register with the platform in order to authenticate against the APIs.

CommonData API¶

The CommonData API is used to get general platform values, such as dropdowns or static values, that don't change as often as user-dependent properties or information. These values are used across the entire application and have a longer cache time than other properties, allowing them to be cached internally more effectively.

The most common use case for the CommonData API is to access the Module API. To do this, you need the DataAreaEntity and DataAreaGroup properties:

You also have the possibility to receive dropdown data, e.g. crops or crop types:

Structure of CommonData¶

In most cases, any CommonData-Result will be an ID-to-Value-Pair like this:

{
  "id": "910c8d63-0e3b-4609-be9b-6ed2fad75b84",
  "value": "Harvest & Quality",
  "description": "harvest-quality",
  "key": "HarvestQuality",
  "parent": null,
  "icon": "harvest-quality"
}

The other properties, like description and key, are internally used in HortiView. The icon value represents a MaterialUI-Icon, in case you want to display an icon as well.

Some special cases, like DataAreaGroup and DataAreaEntity, make use of the parent property. It's used to create cascading dependencies to other entities.

A DataAreaEntity contains a parent ID that points to a DataAreaGroup, so we have the possibility to connect both entities:

[DEPRECATED] FarmAdmin¶

Farm Management API

Season and Sensor API¶

Season Admin API

Sensor Admin API

Module Api¶

Data Areas and Consent

To access user data through your module, you need to fulfill the following requirements:

1. Configure the DataAreas you want to access in the Module Creation Process.
2. Configure the ModuleDependencies, you require access to.
3. Obtain the modulePermissionToken, orgId, and your moduleId from the module federation.
4. Get Farm-Data
   1. Retrieve DataArea Groups from the CommonData API.
      1. Get the DataArea Entity you want to access using the related DataArea Group ID (CommonData API).
      2. Access the required Entity via Module API using the Organization ID, Module ID, and Entity ID.
   2. Directly retrieve the DataArea Entity with the FarmOrgEntitiesByName-endpoint and an DataArea-Value
5. Get Module-Data

Make sure to configure the DataConsent and ModuleDependencies, when creating your module in HortiView:

ModulePermissionToken¶

The modulePermissionToken is passed (along with all other BaseProperties) to the module and saved in the BaseProps Store when the ModuleBase is initialized.

29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

export const ModuleBase = ({ props, requiredProps, routes }: ModuleBaseProps) => {
  const { i18n, t } = useTranslation();
  const [open, setOpen] = useState(true);
  const setBaseProps = useBasePropsStore(state => state.setCustomProps);
  const currentLanguage = useBasePropsStore(state => state.currentLanguage);
  // to load the environment config a sourcePath is needed
  const config = useConfigurationStore(state => state.config);
  const queryClient = useQueryClient();

  useSignalRMessages();

  useConfig(props);

  useEffect(() => {
    setBaseProps(props);
    if (!props.standalone) validateProps(props, requiredProps);
    HortiViewService.updateProps(props);

    props.addTranslation({ key: 'debug', value: 'Debugging' });
    props.addTranslation({ key: 'local', value: 'Seasonmanagement' });
    //iterate over every route and add the translation to the translation store
    if (routes) {
      Object.values(routes).forEach(route => {
        const translationKey = route.translationKey;
        if (translationKey)
          props.addTranslation({ key: translationKey, value: t(`routes.${translationKey}`) });
      });
    }

    // invalidate common options to get new language
    invalidateMultipleQueries(queryClient, [['SeasonManagement', 'options']]);
  }, [props, setBaseProps, requiredProps, config, t, routes, queryClient]);

To access the modulePermissionToken, we can simply use the useBasePropsStore hook. This token can be used to access all defined DataArea Groups (via Module API) that you specified during Module Creation, as well as the CommonData API.

Get Farm-Data via the Module API¶

First, we need to find our, what data we want to access. To do so, without worry to much, we can simply receive all dataarea-entities, that are possible to get data from.

To do so, we can either call the following endpoint:

https://app-hv-c-commondata-{env}-weu-001.azurewebsites.net/api/v1.0/dataareaentity/dropdown

OR use the commonoptions-property, to access the dataareaentity-object. (For testing purposes, you can also take a value from Data Areas)

Either way, the result should look similar to this one:

{
  "count": 45,
  "totalCount": 45,
  "items": [
    {
      "id": "978aaeb2-91e7-4dd5-bb7e-8ba9b77b0c63",
      "value": "active_subscriptions",
      "description": "52b57d19-0f02-4a47-b96a-2c4cc575c52a",
      "key": "ActiveSubscriptions",
      "parent": "52b57d19-0f02-4a47-b96a-2c4cc575c52a",
      "icon": ""
    },
    ...,
    {
      "id": "80c9fd4c-2311-40bb-a1ef-ae4033d9e1e8",
      "value": "farms",
      "description": "9e8f1cdd-440d-440a-8a14-25f3f5385c2e",
      "key": "Farms",
      "parent": "9e8f1cdd-440d-440a-8a14-25f3f5385c2e",
      "icon": ""
    },
    {
      "id": "08ca7f97-53c6-4fff-a9f5-e684ffe171a9",
      "value": "irrigation_stations",
      "description": "9e8f1cdd-440d-440a-8a14-25f3f5385c2e",
      "key": "IrrigationStations",
      "parent": "9e8f1cdd-440d-440a-8a14-25f3f5385c2e",
      "icon": ""
    }
  ]
}

Now, we can use the value of the desired entity, to get some data for an organization via your module, with the Module Api:

https://app-hv-c-moduleapi-{env}-weu-001.azurewebsites.net/api/v1.0/{orgId}/FarmOrgEntitiesByName/{moduleId}?dataAreaEntityName=farms

Get Module-Data via the Module API¶

To receive data from other modules, like the Season- or Device-Management, you need to call different endpoints. In contrast to the FarmData, where you define DataAreas, that you need to access, you need to define depencencies within your ModuleCreation-Process, to get access to the corresponding data.

To do so, we need to use to different endpoints this time:

/api/v1.0/{orgId}/ModuleDependencies/{moduleId}

[
  {
    "moduleId": "98097e68-efae-4f89-9353-abcdef123456",
    "registeredEntityName": "BlockPlantLayout",
    "id": "1ffc30b8-4c9d-4eac-aff2-0d12b10bb853"
  },
  {
    "moduleId": "98097e68-efae-4f89-9353-abcdef123456",
    "registeredEntityName": "Season",
    "id": "89558db1-0225-4891-ba3f-974e4af1b57d"
  }
]

/api/v1.0/{orgId}/ModuleDependedEntitiesByName/{moduleId}?entityName={registeredEntityName}

[
  {
    "entityName": "season",
    "season": {
      "startDate": "2025-01-29T00:00:00+00:00",
      "endDate": null,
      "seasonStateId": "5e9e38c5-a775-4fff-b579-81e8a04c3188",
      "cropSeasonName": "Test-Tomatoes-Albrice-2025-01",
      "cropId": "e6fcac72-5885-45ec-8e92-fb8e1754300c",
      "cropTypeId": "73f60df8-b937-4d3f-9e44-268aefcad34e",
      "cropVarietyId": "132ea7de-b1e6-4c40-90ca-e05fd996f7c1",
      "rootstockId": "5ac99572-8524-4972-95e7-d795c193c30f",
      "farmId": "21f035a3-09bf-4ba6-a5a0-abcdef123456",
      "fieldId": "6ffc7970-bcff-49ba-a442-abcdef123456",
      "id": "92eaf2cb-1cc1-477c-ba90-abcdef123456"
    },
    "blockPlantLayout": null,
    "id": "92eaf2cb-1cc1-477c-ba90-abcdef123456"
  }
]

Example Implementation to Access Data via the Module API¶

First, we need to access the DataAreaGroups and DataAreaEntities that can be accessed. The useOptions hook implements an API call for the specified entity.

13
14
15
16
17
18
19

export const useFarmOrgEntities = <T>(
  entity: FarmOrgEntityTypes,
  enabled = true
): { data: T[]; isLoading: boolean } => {
  const moduleId = useBasePropsStore(state => state.moduleId);
  const { data: dataarea } = useOptions('dataareagroup');
  const { data: dataareaentity } = useOptions('dataareaentity');

21
22
23
24
25
26
27
28
29
30
31

  const farmEntityId = useMemo(() => {
    // as long as there is no data return
    if (!dataarea || !dataareaentity) return undefined;

    // get areaId for 'Farm Organization'
    const areaId = dataarea.find(a => a.key === 'FarmOrganization')?.id;
    if (!areaId) return undefined;

    const eId = dataareaentity.find(e => e.description === areaId && e.value === entity)?.id;
    return eId;
  }, [dataarea, dataareaentity, entity]);

33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

  const result = useBasicQuery(
    {},
    () => getFarmOrgEntities<FarmOrgEntity[]>(moduleId, farmEntityId ?? ''),
    entity,
    enabled && !!moduleId && !!farmEntityId
  ) as UseQueryResult<FarmOrgEntity[], Error>;

  return {
    ...result,
    data: (result.data ?? [])
      .map(farmOrgEntity => {
        const key = FarmOrgEntityTypeResultMap[entity];
        return farmOrgEntity[key as keyof FarmOrgEntity];
      })
      .filter(Boolean) as T[],
  };
};

This function calls the "Module API"-Endpoint like this:

https://app-hv-c-moduleapi-tes-weu-001.azurewebsites.net/{OrgId}/FarmOrgEntities/{ModuleId}/{EntityId}

Data Areas¶

If your module needs to access data, it requires to have access to the data area, where the data is included. We refer to those as "DataAreaGroups".

Example: If you want to access Farms, you need to have access to the DataAreaGroup called Farm Organization Definition. The relation between DataAreaGroups and DataAreaEntities is described in Common Data

We have the following data areas available right now (as of 23^rd of may 2025):

Farm Business Management¶

{
    "value": "farm_data_area_consents",
    "key": "FarmDataAreaConsents"
},
{
    "value": "farm_organizations_subscriptions",
    "key": "FarmOrganizationSubscriptions"
},
{
    "value": "invoice_items",
    "key": "InvoiceItems"
},
{
    "value": "invoice_management",
    "key": "InvoiceManagement"
},
{
    "value": "invoices",
    "key": "Invoices"
},
{
    "value": "legal_documents_farm_acceptances",
    "key": "LegalDocumentsFarmAcceptances"
},
{
    "value": "subscriptions",
    "key": "Subscriptions"
},
{
    "value": "subscription_types",
    "key": ""
}

Farm Organization Definition¶

{
    "value": "alert_rules",
    "key": "AlertRules"
},
{
    "value": "farm_organizations",
    "key": "FarmOrganizations"
},
{
    "value": "farms",
    "key": "Farms"
},
{
    "value": "fields",
    "key": "Fields"
},
{
    "value": "irrigation_stations",
    "key": "IrrigationStations"
},
{
    "value": "zones",
    "key": "Zones"
}

Farm Organization Member¶

{
    "value": "farm_members",
    "key": "FarmMembers"
},
{
    "value": "farm_roles",
    "key": "FarmRoles"
},
{
    "value": "field_members",
    "key": "FieldMembers"
}

Membership in Organization¶

{
    "value": "farm_members",
    "key": "FarmMembers"
},
{
    "value": "field_members",
    "key": "PersonalAssociationFieldMembers"
},
{
    "value": "vendor_members",
    "key": "PersonalAssociationVendorMembers"
}

Personal Information¶

{
    "value": "users - (addresses + countries)",
    "key": "UsersWoAddressesWoCountries"
}

Device Administration¶

{
    "value": "ADMA",
    "key": "AdmaMasterDataAdma"
}

Sensor Streams¶

{
    "value": "ADMA",
    "key": "AdmaSensorsAdma"
}