Contents
-
Writing Tachyon Instructions
-
Integrating with Tachyon
-
Introduction
-
Tachyon RunInstruction command-line tool
-
Consumer API reference
-
Using scope and filter expressions
-
How to guides
-
Add and remove Instruction Definitions and organize them into Instruction Sets
-
Find the right instruction definition
-
Getting data from Tachyon clients
-
Handling errors returned by Tachyon
-
Issue an instruction, track its progress and retrieve responses
-
Set up in instruction to be executed on a schedule
-
Set up Principals, Roles and Permissions, for Tachyon version 8.0 and later
-
Set up Principals, Roles and Permissions, up to and including Tachyon version 5.2
-
Add and remove Instruction Definitions and organize them into Instruction Sets
-
Introduction
-
Tachyon .NET Consumer SDK
-
Tachyon PowerShell Toolkit
-
Index
Find all computers
The most basic use case is finding every computer Tachyon knows about:
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer/Devices will return this response: | Use Devices object inside the Tachyon connector instance and call GetDevices without any parameters. The devices object contains the same data as the JSON response on the left. |
Finding a specific computer or computers
To find a specific computer or computers matching specific criteria, you should use a filter expression.
Filtering and sorting with pagination
The device's API supports standard filtering, sorting and pagination methods seen throughout the Tachyon Consumer API to find computers matching specific parameters. See API reference for a list of the columns you can sort and filter.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a POST request with the following payload: Returns this response: | Use devices object inside the Tachyon connector instance and call GetDevices, while passing in an object containing filtering and sorting specification. devices object contains the same data as the JSON response on the left. |
Finding specific computers
A computer has two properties that on their own should be enough to identify it:
- Fully Qualified Domain Name (FQDN) - each FQDN in an organization should be unique
- Tachyon GUID - created by the Tachyon Agent to uniquely identify a computer.
You can use either FQDN or Tachyon GUID to locate a specific computer.
In edge cases, a computer might be replaced (for example, during an upgrade) and the new computer given the same FQDN . Although the FQDN will be identical, the Tachyon GUID will be different as it's created during the Tachyon Agent install on a new computer.
Finding a Device by its Fully Qualified Domain Name (FQDN)
Because machine's FQDN might contain characters that are not URI-friendly, FQDN sent to the Consumer API has to be Base64 encoded.
If I wanted to look for a computer whose FQDN is "Somemachine.somedomain.com", I would have to base64 encode it and use the encoded string as parameter in the API call.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer/Devices/fqdn/U29tZW1hY2hpbmUuc29tZWRvbWFpbi5jb20= will yield following response: | Here FQDN doesn't have to be Base64 encoded because the SDK performs the encoding internally. Use Devices object inside the Tachyon connector instance. Device object contains the same data as the JSON response on the left. |
Finding a Device by its Tachyon GUID
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer/Devices/tachyonguid/1D8863621D374BBB9E39CABA431593AD | Use devices object inside the Tachyon connector instance. device object contains the same data as the JSON response on the left. |
Finding management groups for computers
Tachyon supports organizing computers into management groups. A single computer can belong to many groups and at least belong to the All Devices group. All computers belong to the All Devices group by default and cannot be removed from it.
Management groups affect how instructions are targeted , so it's helpful to find out what groups computers belong to . You can do this by looking a computer up by its FQDN or Tachyon GUID as described in finding a specific computer.
By Fully Qualified Domain Name (FQDN)
Just as before, we have to use base64 encoded FQDN.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer/Devices/fqdn/U29tZW1hY2hpbmUuc29tZWRvbWFpbi5jb20=/ManagementGroups | Use Devices object inside the Tachyon connector instance. Device object contains the same data as the JSON response on the left. |
By Tachyon GUID
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer/Devices/tachyonguid/1D8863621D374BBB9E39CABA431593AD/ManagementGroups | Use Devices object inside the Tachyon connector instance. Device object contains the same data as the JSON response on the left. |
Find computers matching scope
Using scope allows you to limit which computers receive an instruction. Read defining the scope to find out more about how scope works, and narrowing the scope for examples.
Although using scope can seem like filtering, there are some differences, for example scope:
- Supports tags and management groups while regular filtering does not
- Does not support sorting or pagination so all results are returned in one go.
Some differences relate to the intended use of both features, for example:
- Filtering's design allows you to view the estate
- Scope's design allows you to narrow the target device audience of an instruction.
Scope expressions are standard Tachyon filter expressions. To find out more, read using scope and filter expressions and defining a filter.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a POST request with following payload: Returns this response: | Use Device object inside the Tachyon connector instance. Devices object contains the same data as the JSON response on the left. |
Find an approximate target for an instruction
When issuing instructions, think about your permissions, as they limit which management groups you can target.
An approximate target:
- Is calculated in the context of a specific instruction definition
- Accepts an optional scope expression
- Gives you an overview on how the instruction you're about to issue will affect your estate.
Returned information is aggregated by computer and operating system type. You cannot configure this aggregation.
The following example is using the "1E-Explorer-TachyonCore-InstalledOS" instruction definition. This instruction definition has an Id of 124 on my Tachyon installation, so if I would like to know what part of the estate would be affected if I sent this instruction, I should use this Id when making the reques.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a POST request to https://my.tachyon.server/Consumer/Devices/approxtarget/124 without any payload returns this response: | Use Devices object inside the Tachyon connector instance. Statistics object contains the same data as the JSON response on the left. |
To check the effect the same instruction has on my estate when issued with a scope I should add the scope to the request's payload:
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a POST request with following payload: Returns following response: | Use Devices object inside the Tachyon connector instance. Statistics object contains the same data as the JSON response on the left. |