Documentation

Services pass entity data to a service and save the returned value in a target field of existing or newly generated items. They are used to get authority data from reconciliation services, coordinates from geocoding services or codings and summaries from LLM services.

Services for properties are configured inside the target field configuration, e.g. in the norm_data field configuration. For articles, the configuration should be added to the source item configuration. The resulting service buttons below a field or item can either be manually clicked by users or triggered by batch operations using the mutate button.

The services configuration for properties is added to the target field. It is an object with an arbitrary key for each service and a service configuration object as value. The configuration object for property fields contains the following keys:

Key	Description
caption	Button caption
service	Service name. At the moment only `reconcile` is supported.
provider	An identifier for the reconciliation provider. The provider has to be configured in the app settings of Epigraf by an administrator. Examples: `aat`, `wd`.
input	The field that is used to query the service, e.g. `lemma`. In properties, you can use `path` to send the full lemma path to the service.
type	An additional type send to the reconciliation service, e.g. `/aat` or `Q18783400`.
score	For batch reconciliation, the score threshold to be passed. From the result list, the first item either marked as match by the service or passing the threshold is inserted into the norm_data field.

In the example, geo data is stored in the content field of a property:

 "content": {
     "caption": "Geokoordinaten",
     "showcaption": false,
     "format": "geodata",
     "widgets": {
       "map": true
     },
     "keys": {
       "lat": "Latitude",
       "lng": "Longitude",
       "radius": "Radius"
     },
     "template": "list",
     "services": {
       "geo": {
         "caption": "Geocoding",
         "service": "geo",
         "provider": "nominatim",
         "input": "lemma"
       }
     }
   }

Make sure to configure the articles and items to show geo data. For example, if the geo data is contained in properties that are used in places items:

Set the geodata key of the articles type to {"places": "property.content"} to show locations on the articles overview map.
Set the geodata key of the items type to property.content to show locations within an article.

 "services": {
        "aat": {
          "caption": "Reconcile AAT",
          "service": "reconcile",
          "provider": "aat",
          "type": "/aat",
          "input": "lemma",
          "score": 20
        },
        "wd": {
          "caption": "Reconcile WikiData",
          "service": "reconcile",
          "provider": "wd",
          "type": "Q18783400",
          "input": "lemma",
          "score": 20
        }
      }

Make sure to configure the namespaces within the property type configuration to generate links.

The services configuration for articles is added to the source item. It is an object with an arbitrary key for each service and a service configuration object as value. The configuration object for items contains the following keys:

Key	Description
caption	Button caption
service	Service name. At the moment only `llm` is supported. This uses the [Databoard Service](https://databoard.uni-muenster.de/) at the University of Münster.
task	The task to be performed by the LLM service, one of `summarize`, `coding` or `annotate`. See the [databoard documentation](https://databoard.uni-muenster.de/) for details.
prompts	Optionally, a prompt template supported by the service. Defaults to an empty string for default prompts. See the [databoard documentation](https://databoard.uni-muenster.de/) for details.
multinomial	Whether to perform the task in single or in multi mode. Coding tasks return the best matching property in single mode and a value for each property in multi mode. See the [databoard documentation](https://databoard.uni-muenster.de/) for details.
input	Either the whole article is sent to the service in Markdown format (`article`) or the content of the item with the service configuration (`item`). Artikel data is taken from the last saved state while item content ist taken directly from the field in an open article.
target	An object with the keys container, itemtype, sectiontype and fields. The container value determines whether to update the source item (`item`), add or update other items in the same section (`section`) or other items other sections of the article (`article`). Item type and section type determine which items and sections are affected inside the container. The item fields where the result should be stored. For summarize tasks, defaults to `{"content": "llm_result", "value": "state"}`. For other tasks such as coding it defaults to `{"properties_id": "properties_id", "properties_label": "properties_label", 'value': "value"}`.
tagname	For annotation tasks the name of the links configuration that will be used to add intext annotation. The property type is derived from the links configuration.

"services": {
  "summary": {
    "caption": "Automated summary",
    "service":"llm",
    "task": "summarize",
    "input": "article",
    "target": {
      "container": "item",
      "fields": {
        "content": "llm_result",
        "value": "state"
      }
    }
  }
}

Add the following configuration to the item that contains the source text:

"services": {
  "coding": {
    "caption": "Genre detection",
    "service": "llm",
    "task": "coding",
    "input": "item",
    "target": {
      "container": "article",
      "itemtype": "categories",
      "sectiontype": "categories"
    },
    "fields": {
      "properties_id": "properties_id",
      "properties_label": "properties_label",
      "value": "value"
    }
  }
}

In the item type used in the configuration ("categories") configure the property field and link it to a property type. The properties are used to create the rule book.

The result is inserted into the article section defined in the sectiontype value. If a section can hold multiple items (count is set to *), one item for each answer is added. Otherwise the first matching item is updated.

Service URLs and access tokens need to be configured in the app.php. See the developer documentation.

Access to a services needs to be explicitly allowed. Add the following permission record for a user or role:

Field	Setting
permission type	Allow access.
entity name	The service name (http, llm, reconcile, geo) or an asterisk as wildcard.
endpoint	Select the services endpoint `app/services/get`.

All other permission fields remain empty.

How to configure a service for properties?

Field configuration

Example: Geocoding of properties

Example: Reconciliation of authority data for properties

How to configure a service for article data?

Item configuration

Example: Generate summaries with a Large Language Model

Example: Automated coding with a Large Language Model

How to make a service available in Epigraf?

Application settings

Permissions