Documentation
¶
Overview ¶
Package sharepoint integrates Microsoft SharePoint as a server-registered Atlas worker: a BPMN SharePoint task creates a list item in a model-authored site and list through a configured provider via the job path (ADR-0141), mirroring how the mail package delegates a send to a registry-managed provider (ADR-0079). The integration inherits the job protocol's durability and non-blocking properties (ADR-0007):
- A task creates a job carrying the reserved compiler.SharePointJobType. The processor never performs the outbound call itself, so it stays allocation-free (invariant I1) and free of any HTTP dependency.
- The in-process Handler — a job worker — pulls those jobs, creates the item off the processor goroutine and after fsync (invariant I2, never inside applyToState / I4), and completes the job (writing the created item's JSON into the task's result variable), which drives the token onward.
- The Graph base and OAuth credential live in a server-side Registry keyed by worker name, so a model refers to a provider by name only and never carries an endpoint or a secret (ADR-0036/0041). Only the target (site, list, item fields) is authored in the model, like a REST task's endpoint (ADR-0067).
The transport is Microsoft Graph (GraphClient), authenticated with an OAuth2 bearer token acquired app-only (client-credentials) or via a pre-obtained refresh token (ADR-0141), reusing the same grant shapes as the native mail providers (ADR-0093).
Delivery is at-least-once: a crash between "Graph created the item" and "job completed" replays the create, which — unlike an idempotent mail Message-ID — can produce a duplicate list item. De-duplication of created items is a follow-up (ADR-0141).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
func Handler(store state.Reader, lookup ProcessLookup, reg *Registry) job.OutputHandler
Handler builds a job handler that performs a SharePoint worker task. Register it with a job.Runner under the reserved compiler.SharePointJobTypeIndex via HandleWithOutput; the runner then pulls activatable SharePoint jobs, and for each the handler resolves the task's connector/site/list/fields from the compiled process — evaluating any FEEL value over the variables the task sees, up its scope chain (the fx toggle, ADR-0067) — resolves the named worker's Graph client from reg, creates the list item, and (when the task names a result variable) returns the created item's JSON as that variable to be written back on completion. Returning an error leaves the job pending (retry, then an incident, ADR-0061); the runner completes it only on success.
Types ¶
type Client ¶
type Client interface {
CreateItem(ctx context.Context, req ItemRequest) (any, error)
}
Client creates a list item through one configured SharePoint provider. It is an interface so the worker is testable without a live server and so a worker name binds to exactly one provider. CreateItem returns the created item as decoded JSON (the shape Graph returns), which the worker writes into the task's result variable.
func NewProviderClient ¶
func NewProviderClient(cfg ProviderConfig) (Client, error)
NewProviderClient builds the SharePoint client for a managed worker: it parses the credential bundle, applies the Graph token-endpoint and scope defaults, builds an OAuth token source, and returns a Graph client. A misconfigured worker returns an error so the caller can skip it (its tasks park) rather than acting wrongly. This is the single place a provider variant would be added.
type GraphClient ¶
type GraphClient struct {
// contains filtered or unexported fields
}
GraphClient creates SharePoint list items through the Microsoft Graph API (ADR-0141). It POSTs {fields:{…}} to /sites/{site}/lists/{list}/items with a bearer token from its TokenSource, and returns the created item as decoded JSON.
func NewGraphClient ¶
func NewGraphClient(tokens TokenSource, baseURL string) *GraphClient
NewGraphClient builds a SharePoint Graph client. baseURL defaults to the Graph v1.0 API when empty.
func (*GraphClient) CreateItem ¶
func (c *GraphClient) CreateItem(ctx context.Context, req ItemRequest) (any, error)
CreateItem creates a list item in the worker's site/list and returns the created item decoded from Graph's JSON response. A missing site or list, or a non-2xx response, is an error so the job stays pending and is retried (at-least-once).
type ItemRequest ¶
ItemRequest is one list-item creation a SharePoint task performs. Site and List address the target list (a Graph site id and a list name or id); Fields are the item's column values, already resolved from the model's literal-or-FEEL values by the worker. RequestID is the job key, carried for tracing and any future idempotency support.
type Job ¶ added in v0.5.0
type Job struct {
// Connector names the SharePoint instance in the worker's registry — the Graph
// endpoint and the OAuth bundle live there, never here.
Connector string `json:"connector"`
// Site and List address where the item is created. They are model data
// (ADR-0141), evaluated against the instance's variables.
Site string `json:"site,omitempty"`
List string `json:"list,omitempty"`
// Fields is the item to create, each value already coerced to the string form
// Graph's list-item fields take.
Fields map[string]string `json:"fields,omitempty"`
// RequestID is the job key, sent so an at-least-once retry is recognizable to
// Graph as the same request. It is frozen at resolve time rather than recomputed
// where the retry happens, so a retried job carries the key of the job it retries.
RequestID string `json:"requestId,omitempty"`
// Result names the process variable the created item is written to; empty
// discards it.
Result string `json:"resultVariable,omitempty"`
}
Job is a SharePoint task with everything the engine can evaluate already evaluated.
func Resolve ¶ added in v0.5.0
func Resolve(store state.Reader, cp *compiler.CompiledProcess, detail *compiler.ConnectorTaskDetail, ei *model.ElementInstanceValue, elementInstanceKey, jobKey uint64) (Job, error)
Resolve turns a compiled SharePoint task into a Job. Engine work by necessity: FEEL is compiled at deploy (ADR-0008/0015) and the scope lives in the store.
type ProcessLookup ¶
type ProcessLookup func(defKey uint64) *compiler.CompiledProcess
ProcessLookup resolves a process-definition key to its compiled process. The worker uses it to find the worker name, site, list, and item fields a SharePoint job belongs to, so one handler serves every deployed process.
type ProviderConfig ¶
ProviderConfig is the per-connector data the server resolves before building a client: an optional Graph base override (Endpoint) and the resolved Secret — the OAuth credential JSON bundle held in the vault under the worker's credentialsRef (ADR-0141). The secret lives only here at build time, never in a model or an event (I6).
type Registry ¶
Registry resolves a worker name to the Client for this kind. Workers are registered at the server from managed configuration (endpoint plus credentials), so a model refers to a worker by name only (ADR-0036/0041).
It is the shared clientreg.Registry, which also carries *why* a configured worker is missing from it — the difference between "never configured" and "configured and broken", which is what a parked token has to be able to say (ADR-0158).
type Result ¶ added in v0.5.0
Result is what creating an item produces: the item as Graph returned it, and the variable it belongs in.
func Run ¶ added in v0.5.0
Run creates the item through the caller's own registry. The in-process path calls it too, so there is one definition of what a resolved SharePoint task means rather than two that drift — only which instances are in reach differs.
func (Result) Variables ¶ added in v0.5.0
func (r Result) Variables() []model.VariableValue
Variables renders a run's result as the process variables the job completes with — none when the model named no result variable. Both halves call it, so an offloaded create and an in-engine one cannot disagree about what a SharePoint task returns.
type TokenSource ¶
type TokenSource = oauth2.TokenSource
TokenSource yields a valid OAuth2 bearer access token for the Graph API. The mechanism — caching, refresh timing, the token exchange — is the shared oauth2 package's; what stays here is this worker's policy: which grants it accepts and what its credential bundle looks like.
Source Files