Service Readme Template

Service README template

A compact description of what service does.
Report Bug · Open PR

📖 Description

Short description that explains what this service does in high level:

• Which problem does it solve
• How does this service get triggered
• What does the service do
• ...

📦 Related services

This service helps manage the consumer-producer flow. The following services are closely related to this one:

• some-related-service
• another-related-service

(back to top)

⏩ Quick setup

🐋 Docker-compose.yml

  my_service: 
    image: lblod/my_service
    volumes:
	  - ./some/config/path:/config
    labels:
	  - "logging=true"
    restart: always
    logging: *default-logging

🗒️ Config

If other basic configuration is needed, specify here. Just the minimum to make it work. E.g. setup delta-notifier, auth rules. Leave advanced stuff for the advanced section below.

(back to top)

🔑 Environment variables

ENV	description	default	required
EXAMPLE_ENV	This env is just an example	true	X
ANOTHER_ENV	And another one	http://mu.semte.ch/application

(back to top)

🐸 Gotcha's

This section explains things you dont want to have missed. Common pitfals. E.g:

• You have to wait for the migrations to complete before you can make a request
• This service wait for X in service Y to complete. Make sure that one completes BEFORE you trigger this service or you have to restart the stack

The point of this section is to already give the user a headsup of certain issues/pitfals that you might have encountered while testing/developing this service and said to yourself: "whoever uses this service should know this or they will keep searching and searching..."

🧠 Advanced

The advanced section is used to go a bit more in depth. It explains possible config files, how to setup stuff, how to test, API's and other topics. The paragraph you are currently reading can be removed.

Configuration

You manage X and Y by creating a folder containing json files with config options. A basic option has been given above, here is a more advanced configuration to fit your needs.

Setup graph filters

/config/service-name/config/export.json

{
  "export": [
    {
      "type": "http://data.vlaanderen.be/ns/besluit#Agendapunt",
      "graphsFilter": [ "http://mu.semte.ch/graphs/public" ],
      "properties": [
        "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
        "http://mu.semte.ch/vocabularies/core/uuid",
        "http://data.vlaanderen.be/ns/besluit#aangebrachtNa",
        "http://purl.org/dc/terms/description",
        "http://data.vlaanderen.be/ns/besluit#geplandOpenbaar",
        "http://data.vlaanderen.be/ns/besluit#heeftOntwerpbesluit",
        "http://purl.org/dc/terms/reference",
        "http://purl.org/dc/terms/title",
        "http://data.vlaanderen.be/ns/besluit#Agendapunt.type"
      ]
    }
  ]
}

type: type should match the resource type graphsFilter: Graphs filter is a filter for graph or something. properties: properties control the output properties.

Be carefull when specifying graphsfilter as enterig the wrong one leaves might leak sensitive data

(back to top)

🔬 Testing

Export flow

After setting up the service, you can following these steps to test if everthing works

1. Add a config with you resource
2. docker-compose up -d
3. Create a new resource in the frontend
4. check the logs docker-compose logs --tail=100 -f my_service. You should see a line in the logs saying: The service has succesfully exported ${service_key}
5. Check the data/files/export folder and see if the new resource file has been created
6. Wait for the other service to get triggered
7. open the frontend and see if it flowed through correctly

Healing flow

1. Add a config with you resource
2. break the data using the following query

DELETE {
 GRAPH ?g {
  ?s some:predicate ?o
} WHERE {
GRAPH ?g {
  ?s a some:type;
   ?p ?o.
}

3. trigger the healing job with curl –location –request POST ‘127.0.0.1/heal’ –header ‘Content-Type: application/json’
4. Check service logs and look for following line Resource X succesfully healed
5. Check in frontend if everything is still working

(back to top)

🛠️ Development

Information on how to setup development. Preferable with code examples

 my_service:
   image: lblod/my_service:0.0.1
   ports:
     - 8888:80
     - 9229:9229
   environment:
     NODE_ENV: "development"
     IMPORTANT_ENV: "true"
   volumes:
     - ./data/files:/share
   logging: *default-logging

Make sure you set port X to 8890 and check if something something. Trigger the service manually by doing X Y Z

(back to top)

API

/trigger-export

Triggers the whole export flow

Request body

N/A

Response

201 Created

(back to top)

### Usefull Queries

List all exported resource

SELECT ?exported WHERE {
 ?exported a some:type;
   some:status "EXPORTED"
}

Show exported resources and their status

SELECT ?exported ?status WHERE {
 ?exported a some:type;
   some:status ?status
}

Purge all resources

DELETE WHERE{
 ?exported a some:type;
   some:status "EXPORTED"
}

(back to top)