Bewijs toevoegen

Het grootste deel van deze handleiding gaat over het lezen van data, maar de API kan via mutations ook data wegschrijven. Deze pagina doorloopt een volledig voorbeeld: een eigen integratie die een bewijsbestand aan een maatregel toevoegt door een uitvoeringstaak aan te maken en het bestand daaraan te koppelen.

Warning

Mutations vereisen een token met schrijfrechten. Authenticeer via de Device Authorization Grant, zodat het token namens een gebruiker met de rol Regular User of Super User handelt. Read-only machine-to-machine-credentials kunnen geen mutations uitvoeren.

Hoe het werkt

Bewijs in Tidal Control is een document dat aan een activiteit is gekoppeld. Bewijs aan een maatregel toevoegen bestaat uit vier stappen:

Zoek de maatregel waaraan je bewijs wilt toevoegen
Upload het bewijsbestand als document
Maak een uitvoeringstaak aan die aan de maatregel is gekoppeld
Koppel het document als bewijs aan de task

Stap 1: De maatregel zoeken

Zoek de maatregel op naam om het id op te halen:

query FindControl($filter: ControlFilter) {
  controls_paged(first: 1, filter: $filter) {
    edges {
      node {
        id
        sequenceId
        name
      }
    }
  }
}

Variabelen:

{ "filter": { "search": "Access control policy" } }

Stap 2: Het bewijsbestand uploaden

Documenten worden geüpload via een REST-endpoint (geen GraphQL), als multipart/form-data op het veld files. Gebruik hetzelfde Bearer-token:

curl -s -X POST https://portal.tidalcontrol.com/documents \
  -H "Authorization: Bearer {access_token}" \
  -F "files=@evidence.pdf"

Het antwoord is een array van de geüploade documenten:

[
  {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "evidence.pdf",
    "type": "application/pdf"
  }
]

Bewaar het document-id voor de volgende stappen.

Info

De maximale uploadgrootte is 128 MB per verzoek. Je kunt meerdere bestanden in één verzoek uploaden door het veld files te herhalen.

Stap 3: Een uitvoeringstaak op de maatregel aanmaken

Maak een uitvoeringstaak aan en koppel deze via het veld controls aan de maatregel uit stap 1:

mutation CreateExecution($input: ExecutionInput!) {
  addExecution(input: $input) {
    id
    sequenceId
    name
  }
}

Variabelen:

{
  "input": {
    "name": "Quarterly access review",
    "controls": ["22222222-2222-2222-2222-222222222222"]
  }
}

Alleen name is verplicht. controls accepteert een of meer maatregel-id's, en je kunt ook description, expires, owners en assets instellen. De mutation geeft het id van de nieuwe taak terug.

Stap 4: Het bewijs koppelen

Koppel het geüploade document aan de task met addEvidenceToExecution:

mutation AddEvidence($activityId: ID!, $documentIds: [ID!]!) {
  addEvidenceToExecution(activityId: $activityId, documentIds: $documentIds) {
    id
    sequenceId
    evidence {
      id
      document {
        name
      }
    }
  }
}

Variabelen:

{
  "activityId": "33333333-3333-3333-3333-333333333333",
  "documentIds": ["11111111-1111-1111-1111-111111111111"]
}

Het bewijs verschijnt nu op de taak, die aan je maatregel is gekoppeld.

Volledig Python-voorbeeld

Dit script knoopt de vier stappen aan elkaar. Het hergebruikt de get_token()- en graphql()-helpers uit Authenticatie.

import requests

GRAPHQL_URL = "https://portal.tidalcontrol.com/graphql"
DOCUMENTS_URL = "https://portal.tidalcontrol.com/documents"


def find_control(search, access_token):
    query = """
    query FindControl($filter: ControlFilter) {
      controls_paged(first: 1, filter: $filter) {
        edges { node { id sequenceId name } }
      }
    }
    """
    data = graphql(query, {"filter": {"search": search}}, access_token)
    edges = data["controls_paged"]["edges"]
    if not edges:
        raise RuntimeError(f"Geen maatregel gevonden voor '{search}'")
    return edges[0]["node"]


def upload_document(file_path, access_token):
    with open(file_path, "rb") as f:
        r = requests.post(
            DOCUMENTS_URL,
            headers={"Authorization": f"Bearer {access_token}"},
            files={"files": f},
        )
    r.raise_for_status()
    return r.json()[0]  # eerste geüploade document


def create_execution(name, control_id, access_token):
    mutation = """
    mutation CreateExecution($input: ExecutionInput!) {
      addExecution(input: $input) { id sequenceId name }
    }
    """
    data = graphql(
        mutation,
        {"input": {"name": name, "controls": [control_id]}},
        access_token,
    )
    return data["addExecution"]


def add_evidence(activity_id, document_id, access_token):
    mutation = """
    mutation AddEvidence($activityId: ID!, $documentIds: [ID!]!) {
      addEvidenceToExecution(activityId: $activityId, documentIds: $documentIds) {
        id
        sequenceId
        evidence { id document { name } }
      }
    }
    """
    data = graphql(
        mutation,
        {"activityId": activity_id, "documentIds": [document_id]},
        access_token,
    )
    return data["addEvidenceToExecution"]


if __name__ == "__main__":
    token = get_token()
    access_token = token["access_token"]

    control = find_control("Access control policy", access_token)
    document = upload_document("evidence.pdf", access_token)
    task = create_execution("Quarterly access review", control["id"], access_token)
    result = add_evidence(task["id"], document["id"], access_token)

    print(f"'{document['name']}' toegevoegd aan taak #{result['sequenceId']} op maatregel {control['name']}.")

Bewijs aan een bestaande task koppelen

Bestaat er al een geschikte uitvoeringstaak, sla dan stap 3 over. Zoek de taak met de activities_paged-query (zie Taken exporteren) en roep vervolgens addEvidenceToExecution aan met het id.