Query Templates

Modified on Thu, 14 Sep 2023 at 02:18 PM

Article Content

Introduction
Queries
Mutations
Next Steps

Introduction

Below are some example queries to reference related to accessing Altium 365 design data through the Nexar API. Feel free to adapt any of these to suit your use case.

This should help get you started and you can use these examples to build your own queries to get the data you need most efficiently. See How the language works and our data model.

The majority of these queries and mutations require an ID or a URL as input. This means that you might have to use a different query first to get an ID or URL which can then be used in another query/mutation. Here's an example:

Goal: Create a comment thread.

The Creating a comment thread example requires two ID inputs: "entityId" which is a project ID, and a documentId.

To start, use the Workspaces query to retrieve all available workspaces and their projects. Take note of the ID of the project you wish to create a comment thread on.

Use that project ID with the Documents by project query to retrieve all of the documents making up that project and their corresponding document IDs.

With your project ID and document ID, you can now use the Creating a comment thread mutation.

Queries

Workspaces

query workspaces {
  desWorkspaces {
    id
    name
    description
    url
    projects {
      id
      name
    }
  }
}

Workspace by ID

query workspaceByID {
  desWorkspaceById (id: "Your workspace ID") {
    id
    name
    description
    url
    projects {
      id
      projectId
      name
      description
    }
  }
}

Workspace by URL

query workspaceByUrl {
    desWorkspaceByUrl (
        workspaceUrl: "Your workspace URL"
    ){
        id
        name
        url
    }
}

Team members by workspace

query team {
  desTeam (workspaceUrl: "Your workspace URL") {
    users {
      userId
      userName
      email
    }
  }
}

Projects by workspace

query projectsByWorkspace {
  desProjects (workspaceUrl: "Your workspace URL") {
    nodes {
      id
      projectId
      name
      description
      url
    }
  }
}

Projects by ID

query projectById {
  desProjectById (id: "Your project's ID") {
    id
    projectId
    name
    description
  }
}

Searching projects by name

query searchProjectByName {
    desProjects (
        workspaceUrl: "Your Workspace URL",
        where: {
            name: {
                contains: "Your search"
            }
        }
    ){
        nodes {
            id
            name
        }
    }
}

Searching projects by last updated time

query searchProjectByName {
    desProjects (
        workspaceUrl: "Your workspace URL",
        where: {
            updatedAt: {
                gte: "2023-01-01"
            }
        }
    ){
        nodes {
            id
            name
        }
    }
}

Library components by workspace

query library {
  desLibrary (workspaceUrl: "Your workspace URL") {
    components {
      nodes {
        id
        name
        details {
          parameters {
            type
            name
            value
          }
        }
      }
    }
  }
}

Component by ID

query componentById {
  desComponentById (id: "Your component's ID") {
    id
    name
    comment
  }
}

Comment threads by project

query commentThreads {
  desCommentThreads (projectId: "Your project's ID") {
    assignedTo {
      userId
      userName
    }
    commentThreadId
    status
    comments {
      commentId
      text
    }
  }
}

Documents by project

query Project {
    desProjectById (
        id: "Your project ID"
    ) {
        id
        name
        workspaceUrl
        design {
            workInProgress {
                variants {
                    pcb {
                        documentId
                        documentName
                    }
                    schematics {
                        documentName
                        documentId
                    }
                }
            }
            releases {
                nodes {
                    variants {
                        pcb {
                            documentId
                            documentName
                        }
                        schematics {
                            documentId
                            documentName
                        }
                    }
                }
            }
        }
    }
}

Mutations

Creating a comment

mutation createComment {
  desCreateComment (input: {
    commentThreadId: "Your comment thread ID",
    entityId: "Your project ID",
    text: "Your comment text"
  }) {
    commentId
  }
}

Creating a comment thread

mutation createCommentThread {
    desCreateCommentThread (input: {
        documentType: "Your document type (SCHEMATIC or PCB)",
        commentContextType: "Your context type (AREA, COMPONENT, NONE, TRACK or VIA)",
        entityId: "Your project ID",
        documentId: "Your document ID",
        text: "Your comment text",
    }) {
        commentThreadId
        commentId
    }
}

Creating a task

mutation createTask ($projectId: ID!, $taskName: String!, $taskDescription: String!, $priority: DesTaskPriority, $status: DesTaskStatus){
    desCreateProjectTask (
        input: {
            projectId: $projectId
            task: {
                name: $taskName
                description: $taskDescription
                priority: $priority
                status: $status
            }
        }
    ){
        task {
            id
            refId
        }
    }
}

Updating a task

mutation updateTask ($taskId: ID!, $status: DesTaskStatus, $taskName: String, $taskDescription: String){
    desUpdateTask (
        input: {
            taskId: $taskId
            status: $status
            name: $taskName
            description: $taskDescription
        }
    ){
        errors {
            message
        }
    }
}

Creating a task comment

mutation createTaskComment ($taskId: ID!, $text: String!) {
    desCreateTaskComment (
        input: {
            taskId: $taskId
            text: $text
        }
    ){
        comment {
            text
            commentId
        }
    }
}

Next Steps

There is the NexarDeveloper GitHub which contains example applications using these queries.

Repositories to note are the first design query or the design web application example.