Graphql

Userapp

This document is an introduction to the queries and mutations you can use to retrieve data from the userapp

# Permissions

The term permission is a term for any role, userappResource or workflow a user can request. You can get a list of available permissions for the logged in user by using the viewer query. This query can be filtered with a where parameter as well as sorted and paginated with the sort and paging parameters. To find out how to filter the permissions, the best way would be to try the query out in the playground. The following example shows a simple filtering.

query SearchViewerPermissions {
  viewer {
    permissions(
      where: { type: role },
      paging: { limit:5 },
      sort: { by: name, order: ASCENDING }
    ) {
      nodes {
        id
        label
        description
      }
    }
  }
}

This query will return a connection with the first 5 (for the logged in user available) permissions that are of the type role sorted by name ascending.

With the id of a permission you can also request only this particular permission likfe follows:

query FindViewerPermission {
  viewer {
    permission(id: "xxx") {
      id
      label
      description
    }
  }
}

Please check the docs in the playground for further information on the UserappPermission type that is returned by these queries.

To request a permission you can utilize the requestPermission mutation. You have to pass the input parameter, at least containing the id of the permission to request and a reason, which is a string that describes why you want to request the permission. You have the possibility to pass additional parameters like an expirationDate. See the playground docs for more information.

The mutation returns the fields shown below in the example query. The success field tells you if the request was successful. If not, you may check the error field to see what was going wrong. If successful, you can get informatoion on the permission you just requested (with all fields of the type UserappPermission). The recipient field gives you all information of the user the permission was requested for. If you don't pass the id of a user as recipient in the input parameter, the logged in user is used as recipient. The last field is request with that you can query the created UserappRequest.

mutation RequestPermission {
  requestPermission(
    input: {
      id: "xxx",
      reason: "this is why"
    }) {
    success
    permission {
      label
    }
    recipient {
      firstName
      lastName
    }
    request {
      label
    }
    error {
      message
    }
  }
}

You can request a permission for multiple recipients. The mutation requestPermissions, that you have to use for that, works exactly the same as requestPermission, but you can pass an array of ids of recipients:

mutation RequestPermissions {
  requestPermissions(
    input: {
      id: "xxx",
      reason: "this is why",
      recipients: ["USERID1", "USERID2", "USERID3"]
    }) {
    success
    operations {
      permission {
        label
      }
      recipient {
        firstName
        lastName
      }
      request {
        label
      }
      error {
        message
      }
    }
  }
}

The returned result provides a success field that tells you if every single request was successful and an array operations, that contain the same fields as described for requestPermission but for the request for every recipient you passed in the input parameter.

# Tasks

After a UserappPermission was requested, a UserappTask is created by the userapp. Every task is assigned to somebody that has to handle it. You can receive your tasks with the viewer query. You will receive a connection of tasks, which means you can use sorting and paging. Also the where parameter provides some properties to narrow down the results. Please check the playground docs for more details.

query SearchViewerTasks {
  viewer {
    tasks(
      where: { q: "test" },
      paging: { limit: 5 },
      sort: { by: createTime }
    ) {
      nodes {
        id
        label
      }
    }
  }
}

Again you may request a single UserappTask by using the corresponding query and providing an id:

query FindViewerTask {
  viewer {
    task(id: "xxx") {
      id
      label
    }
  }
}

To edit a task that is assigned to you, use the taskAction mutation. It takes an input parameter that has to contain at least of the fields id (the id of the task to edit) and an action field that chooses if you want to approve, deny or refuse the request. Additionally you may provide a comment and a data object that can be used by the userapp for further processing.

mutation TaskAction {
  taskAction(
    input: {
      id: "xxx"
      action: approve
      comment: "that's ok"
      data: { a: "data", b: 2 }
    }
  ) {
    success
    message
  }
}

The response tells you by the success field if the operation was successful and a message provided by the userapp.

# Others

There are more userapp queries you can access via the viewer or user query. As these are self-explanatory they are only listed and will not be described in detail.

# Assignments

Query all or a single UserappAssignment

query SearchViewerAssignments {
  viewer {
    assignments(
      where: { q: "test" }
      paging: { limit: 5 }
      sort: { by: name }
    ) {
      nodes {
        id
        name
      }
    }
    
    assignment(id: "xxx") {
      id
      name
    }
  }
}

# Requests

Query all or a single UserappRequests

query SearchViewerRequests {
  viewer {
    requests(
      where: { q: "test" }
      paging: { limit: 5 }
      sort: { by: createTime }
    ) {
      nodes {
        id
        name
      }
    }
    
    request(id: "xxx") {
      id
      name
    }
  }
}