Centeva.AdamsInterface 2.0.0

Centeva.AdamsInterface

ADAMS API client library for .NET. Wraps the 43 operations the NRC ADAMS document management system exposes, so a consuming application can push and pull content without re-implementing the contract.

Supports Windows Authentication with Kerberos delegation, bearer tokens for OIDC, and a no-auth mode for local development.

Built With

Targets net8.0, net9.0 and net10.0.

Installation

dotnet add package Centeva.AdamsInterface

Configuration

{
  "Adams": {
    "BaseUri": "https://your-adams-server/adams/api/",
    "AuthMode": "Windows",
    "ValidateRequests": true
  }
}

services.AddAdamsClient(configuration);

That reads Adams:AuthMode and wires the matching strategy, so moving an environment to OIDC is a configuration change rather than a code change. To decide in code instead:

services.AddAdamsClientCore(configuration)
        .AddBearerTokenAuthentication();   // or AddWindowsAuthentication / AddNoAuthentication

Usage

Inject IAdamsApiClient and call the operation you need. Everything returns Result<T> from Ardalis.Result.

public class DocumentService(IAdamsApiClient adams)
{
    public async Task<string> AddDraftAsync(string blobPath, CancellationToken ct)
    {
        var result = await adams.Document.AddNewDraft(new AddNewDraft.Request
        {
            DocumentPathAndFileName = blobPath,
            DocumentTitle = "RAI Response",
            SensitivityReviewCompleted = "Yes",
            SunsiDocumentSensitivity = Adams.NonSensitive,
            Availability = Adams.PubliclyAvailable
        }, ct);

        if (!result.IsSuccess)
        {
            // result.Status is Invalid for a request that broke its own rules, Error for
            // anything ADAMS refused. result.Errors carries the ADAMS message.
            throw new InvalidOperationException(string.Join("; ", result.Errors));
        }

        return result.Value.AccessionNumber;
    }
}

How outcomes map

That last row is deliberate. A transport failure is infrastructure breakage rather than an answer from ADAMS; turning it into a Result would hide an outage and defeat any retry policy, which acts on exceptions.

Operations

IAdamsApiClient exposes four groups covering all 43 ADAMS operations.

Every relative path lives in AdamsRoutes, which is the single source of truth for the route contract. A simulated ADAMS server should bind the same constants so the two cannot drift.

Authentication

IAuthenticationStrategy has three implementations, selected by Adams:AuthMode.

Windows (default, and what ADAMS requires today). Resolves the caller's WindowsIdentity from the HTTP context and wraps the call in WindowsIdentity.RunImpersonatedAsync so the Kerberos hop to ADAMS is made as them. Windows-only. Requires IIS with ASP.NET Impersonation and Kerberos delegation to reach a remote ADAMS.

Bearer, for OIDC and OAuth. The package sends tokens; it does not acquire them. Resolution order is a caller-supplied provider, then the inbound Authorization header, then an access_token claim:

services.AddAdamsClientCore(configuration)
        .AddBearerTokenAuthentication(async () => await myTokenService.GetAccessTokenAsync());

None, for local development against a simulated ADAMS.

Background jobs

Header pass-through cannot work outside an HTTP request, so code calling ADAMS from a background job under OIDC must supply a token provider, typically a client-credentials flow. There is no ambient identity to fall back on the way Windows authentication has.

Note the matching Windows behavior: with no HTTP context, the Windows strategy falls back to the process identity, so ADAMS calls from a background job act as the app pool account rather than a user.

Validation

Each request entity ships a FluentValidation Validator describing the ADAMS field contract. AddAdamsClientCore registers them and the client runs them before sending, so a malformed accession number is rejected locally rather than costing a round trip and coming back as an opaque response code.

Set Adams:ValidateRequests to false to bypass, which exists because these rules were written against observed ADAMS behavior rather than a published specification. If ADAMS accepts something they reject, a consumer should not have to wait for a package release.

Local development

The simulated ADAMS server that 1.x bundled into this package has been removed, so the client no longer drags ASP.NET Core MVC into your application or registers routes in it.

It is being rebuilt as Centeva.RpsSimulatedAdams, a standalone container. That is not published yet. Until it is, point development at whatever ADAMS stand-in you already run and turn authentication off against it:

{ "Adams": { "BaseUri": "http://localhost:9070/api/", "AuthMode": "None" } }

Document content

ADAMS reads document content itself; this client never sends bytes. AddNewDraft and AddNewOfficialRecord take DocumentPathAndFileName, which is a container-relative logical path inside the configured Azure Blob Storage container - for example /NRR/RAI App/EPID-12345/response.pdf. There is no scheme, host, container name or SAS token in it; ADAMS knows the account and container out of band and resolves the rest.

Write the file to storage before calling ADAMS.

Upload workflow

The order matters, because ADAMS resolves the content and the folder tree as it goes.

// 1. Put the file in storage where ADAMS can reach it.
await objectStorage.WriteAsync(StoragePath.Combine(destinationFolder, fileName), stream, ct);

// 2. Create the folder path, one segment at a time.
var folder = await adams.Folder.AddNewFolder(new AddNewFolder.Request
{
    ParentFolderPath = "/NRR/RAI App",
    NewFolderName = epid
}, ct);

// 3. Create a package, if the documents are to be released together.
var package = await adams.Package.AddNewPackage(new AddNewPackage.Request
{
    PackageTitle = title,
    Availability = Adams.PubliclyAvailable
}, ct);

// 4. Add the document, referencing the path written in step 1.
var document = await adams.Document.AddNewDraft(new AddNewDraft.Request
{
    DocumentPathAndFileName = $"{destinationFolder}/{fileName}",
    DocumentTitle = title,
    SensitivityReviewCompleted = "Yes",
    SunsiDocumentSensitivity = Adams.NonSensitive,
    Availability = Adams.PubliclyAvailable
}, ct);

// 5. File it into the package or the folder.
await adams.Package.FileIntoPackage(new FileIntoPackage.Request
{
    DocumentAccessionNumber = document.Value.AccessionNumber,
    PackageAccessionNumber = package.Value.AccessionNumber
}, ct);

// 6. Submit to DPC, if it should be released.
await adams.Package.SubmitToDpcForNormalProcessing(new SubmitToDpcForNormalProcessing.Request
{
    AccessionNumber = package.Value.AccessionNumber
}, ct);

Check IsSuccess on each step. The sequence is not transactional: a failure partway through leaves the folder, package and documents already created in ADAMS.

Running tests

dotnet test Centeva.AdamsInterface.slnx

Contributing

Branch from master, open a pull request. CI builds and tests against all three target frameworks. Releases are cut by publishing a GitHub Release tagged vX.Y.Z from master; the tag is the only source of the package version.

License

MIT. See LICENSE.

Platform compatibility

net8.0, net9.0 and net10.0. WindowsAuthenticationStrategy is Windows-only, as Kerberos impersonation has no cross-platform equivalent; the bearer and none strategies run anywhere.