mfiles-grpc-go

module
v0.2611.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: MIT

README

M-Files gRPC API client for Go

The Go module github.com/M-Files/mfiles-grpc-go for the M-Files gRPC API, with runnable examples: a quickstart and one program per task recipe. The guides on developer.m-files.com embed their code.

go.mod                     the module github.com/M-Files/mfiles-grpc-go
mfiles/                    the code generated from the protos: every service, message and enum
mfilesclient/              helpers: channel, metadata, login (also through the browser), errors,
                           value builders, token cache
examples/quickstart/       connect, log in, list the 10 newest documents, log out
examples/recipes/<name>/   one program per task
generate.ps1, .sh          generate mfiles/ from the protos
run-tests.ps1              runs the unit tests, the quickstart and every recipe against a vault

The module is a preview: its helpers can still change between releases.

Install

The version for your server (see Versions):

go get github.com/M-Files/mfiles-grpc-go@v0.2611     # the newest revision for 26.11
import (
	"github.com/M-Files/mfiles-grpc-go/mfiles"
	"github.com/M-Files/mfiles-grpc-go/mfilesclient"
)

Go 1.26 or later (google.golang.org/grpc v1.85.0 requires it). The generated package is large; the first build takes a while, later builds are cached.

Build from this folder

In the API bundle and in the M-Files repository, mfiles/ is generated from the protos first. That needs protoc, or Python with grpcio-tools (pip install grpcio-tools), which includes it, and the Go plugins for protoc:

go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.12
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.6.2
.\generate.ps1                      # Windows PowerShell
./generate.sh                       # bash

The scripts look for the protos in $MFILES_PROTO_DIR, then in proto/, then in ../../proto (the layout of the documentation download, where samples/ and proto/ are siblings), then in the M-Files repository's build output. Pass the folder explicitly with -ProtoDir <folder> or as the first argument of generate.sh. They use protoc from PATH (or $PROTOC), else python -m grpc_tools.protoc ($PYTHON selects the interpreter).

To use this folder from a module of your own:

require github.com/M-Files/mfiles-grpc-go v0.0.0
replace github.com/M-Files/mfiles-grpc-go => ../path/to/this/folder

Configure

mfilesclient.ConfigFromEnv and the examples read environment variables:

Variable Meaning
MFILES_ADDRESS host:port: myvault.cloudvault.m-files.com:443 in the cloud; the gRPC port of the server on premises, by default 7766
MFILES_TLS true (default) or false for a server without TLS
MFILES_CA_CERT Optional: a PEM file of root certificates to trust, e.g. a self-signed server's
MFILES_VAULT The vault GUID with braces
MFILES_USERNAME, MFILES_PASSWORD M-Files authentication
MFILES_AUTH browser to sign in through the browser with the vault's OAuth plugin, such as M-Files Login Service; then MFILES_VAULT is optional
MFILES_REMEMBER_SIGN_IN true to keep the refresh token of a browser sign-in in Windows Credential Manager
MFILES_TOKEN, MFILES_AUTH_PLUGIN, MFILES_AUTH_SCOPE Or a token from the vault's identity provider, and optionally its plugin and configuration scope
$env:MFILES_ADDRESS = "localhost:7766"; $env:MFILES_TLS = "false"
$env:MFILES_VAULT = "{7BBEA0BC-40D8-4BCB-A67D-8A3ACFBDB575}"
$env:MFILES_USERNAME = "alice"; $env:MFILES_PASSWORD = Read-Host -MaskInput

Examples

go run ./examples/quickstart
go run ./examples/recipes/connect
go run ./examples/recipes/vault_structure [class alias] [property alias]
go run ./examples/recipes/search [class ID] [days] [limit]
go run ./examples/recipes/read_object [object ID] [object type]
go run ./examples/recipes/download_file [document ID] [folder]
go run ./examples/recipes/create_document [--keep]
go run ./examples/recipes/update_properties [--keep]
go run ./examples/recipes/workflow_state [workflow ID] [initial state ID] [target state ID] [--keep]
go run ./examples/recipes/paging [page size]
go run ./examples/recipes/errors
go run ./examples/recipes/login_service [--remember]

The defaults fit the M-Files Sample Vault. Recipes that write create documents whose titles start with [docs-test] and delete them at the end, unless given --keep. login_service signs in through the browser, so a person must be present.

Tests

go test ./...                       # unit tests; no server needed
.\run-tests.ps1 [-Config <file>] [-Section local] [-Programs examples/quickstart]

run-tests.ps1 reads %USERPROFILE%\.mfiles-grpc-docs\test-config.json (section local, user user), sets the MFILES_* variables, generates the code if mfiles/ is missing, builds everything, runs the unit tests and then each program except login_service with go run. It fails if any of them fails.

Notes for Go

  • Enum values carry their type as a prefix: mfiles.Datatype_DATATYPE_TEXT.
  • Each member of a oneof is a wrapper type: &mfiles.TypedValueUnion{Data: &mfiles.TypedValueUnion_Text{Text: "x"}}. Read one with a type switch on GetData(). mfilesclient has constructors (Text, Lookup, ObjID, PropertyCondition, ...) for the common ones.
  • Values of -bin metadata keys are raw bytes in a Go string; gRPC base64-encodes them.
  • A failed call returns *mfilesclient.Error (use errors.As or mfilesclient.AsError); it keeps the gRPC status, so status.Code(err) still works. HResult is the code of the top-level error, Codes the codes of the whole error stack, and Has(code) tests for a code anywhere in it.
  • gRPC does not keep cookies; the helper stores set-cookie values (M-Files Cloud's mfilesmsm) and sends them back in a cookie header on every later call.

Versions

There is one version per M-Files Server release: v0.2611.0 is for 26.11, v0.2611.1 a revision of it, v0.2701.0 for 27.1. (A Go major version above 1 would have to be part of the import path, so the release number is in the minor version.) A version works with its server release and later ones; with an older server, methods that the server does not have fail with Unimplemented.

License

MIT; see LICENSE.

Directories

Path Synopsis
examples
quickstart command
[START quickstart]
[START quickstart]
recipes/connect command
Recipe "connect": the server version and capabilities before logging in, then log in, read the session, keep it alive and log out.
Recipe "connect": the server version and capabilities before logging in, then log in, read the session, keep it alive and log out.
recipes/create_document command
Recipe "create-document": upload a file and create a single-file document from it.
Recipe "create-document": upload a file and create a single-file document from it.
recipes/download_file command
Recipe "download-file": download the files of a document's latest version to a folder.
Recipe "download-file": download the files of a document's latest version to a folder.
recipes/errors command
Recipe "errors": provoke "not found" and "access denied" and show the decoded M-Files errors.
Recipe "errors": provoke "not found" and "access denied" and show the decoded M-Files errors.
recipes/internal/recipe
Package recipe holds what the recipes share: arguments, connecting, printing values and the test documents some recipes create.
Package recipe holds what the recipes share: arguments, connecting, printing values and the test documents some recipes create.
recipes/login_service command
Recipe "login_service": sign in through M-Files Login Service, or the vault's other OAuth plugin, in the browser, then log in to the vault with the token.
Recipe "login_service": sign in through M-Files Login Service, or the vault's other OAuth plugin, in the browser, then log in to the vault with the token.
recipes/paging command
Recipe "paging": read every document, a page at a time, in object ID order.
Recipe "paging": read every document, a page at a time, in object ID order.
recipes/read_object command
Recipe "read-object": an object's latest version and its properties as typed values.
Recipe "read-object": an object's latest version and its properties as typed values.
recipes/search command
Recipe "search": documents of one class modified in the last N days, newest first.
Recipe "search": documents of one class modified in the last N days, newest first.
recipes/update_properties command
Recipe "update-properties": change properties of a document two ways: in one call with an explicit version, and with check out, set, check in.
Recipe "update-properties": change properties of a document two ways: in one call with an explicit version, and with check out, set, check in.
recipes/vault_structure command
Recipe "vault-structure": object types, the classes of documents with their properties, and IDs resolved by alias.
Recipe "vault-structure": object types, the classes of documents with their properties, and IDs resolved by alias.
recipes/workflow_state command
Recipe "workflow-state": read a document's workflow states and transitions, then move it to another state.
Recipe "workflow-state": read a document's workflow states and transitions, then move it to another state.
api
Package mfilesclient connects to the M-Files gRPC API: it creates the channel, adds the call metadata M-Files expects, logs in and out, and turns failed calls into *Error values that carry the M-Files error code.
Package mfilesclient connects to the M-Files gRPC API: it creates the channel, adds the call metadata M-Files expects, logs in and out, and turns failed calls into *Error values that carry the M-Files error code.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL