24SevenOffice.MappedApi 0.1.1

Mapped 24SevenOffice API

Mapped 24SevenOffice API is a library intended to be reused by various integrations in order to save time implementing common scenarios of interaction with 24SevenOffice WCF SOAP services. This library targets .NET Standard 2.0, which means it's usable both with full .NET framework and .NET core (also other things that .NET Standard 2.0 supports).

You no longer need to

• add service references (instead, they are added within this library!);
• implement identity and session info management (instead, use provided abstractions e.g. ISessionInfo!);
• invent bycicle to properly unit- and integration-test your code (instead, use interfaces!);
• call web-services synchronously (instead, use async/await!)

Core concepts

TfsoApiFactory

TfsoApiFactory is a type that is used to create API service clients. It can be reused because it has no state of it's own.

Service clients

Each service provided by 24SevenOffice can be consumed with corresponding service client. Currently supported 24SevenOffice services:

• Authenticate (IAuthenticateClient implemented by AuthenticateSoapClient)
• AccountService (IAccountClient implemented by AccountServiceSoapClient)
• AttachmentService (IAttachmentClient implemented by AttachmentServiceSoapClient)
• ClientService (IClientClient implemented by ClientServiceSoapClient)
• CompanyService (ICompanyClient implemented by CompanyServiceSoapClient)
• FileService (IFileClient implemented by FileServiceSoapClient)
• FileInfoService (IFileInfoClient implemented by FileInfoServiceSoapClient)
• InvitationService (IInvitationClient implemented by InvitationServiceSoapClient)
• InvoiceService (IInvoiceClient implemented by InvoiceServiceSoapClient)
• PaymentService (IPaymentClient implemented by PaymentServiceSoapClient)
• PersonService (IPersonClient implemented by PersonServiceSoapClient)
• ProductService (IProductClient implemented by ProductServiceSoapClient)
• ProjectService (IProjectClient implemented by ProjectServiceSoapClient)
• SalesOppService (ISalesOppClient implemented by SalesOppServiceSoapClient)
• TemplateService (ITemplateClient implemented by TemplateServiceSoapClient)
• TimeService (ITimeClient implemented by TimeServiceSoapClient)
• TransactionService (ITransactionClient implemented by TransactionServiceSoapClient)

Full list of services is available here.

Service clients shouldn't be reused because there are no thread safety guarantees.

24SevenOffice session and Identities

Upon logging in to 24SevenOffice, you receive a sessionId string. With this library, you actually receive ISessionInfo object.

ISessionInfo

ISessionInfo object is an aggregate of sessionId string, ICredentials and IIdentityCollection objects and UTC timestamp of it's creation date.

This interface was designed to be shallow-immutable.

public interface ISessionInfo
{
    string SessionId { get; }
    ICredentials Credentials { get; }
    IIdentityCollection Identities { get; }
    DateTime CreatedOn { get; }
}

ICredentials

Represents credentials user has logged in with. It may be useful if you want to prolong user session without bothering the user.

This interface is designed to be immutable.

public interface ICredentials : IEquatable<Credentials>
{
    bool IsEmpty {get;}
    string Login { get; }
    string Password { get; }
}

IIdentityCollection

By logging in to 24SevenOffice, you are also assigned an identity, which represents the company you've logged in into. There may be multiple that the user is a part of, hence the identity concept. 24SevenOffice supports switching identities, and to make this easier, IIdentityCollection was created.

The purpose of this interface is to manage the current state of the session regarding identities. When you use AuthenticateSoapClient to log in, or change identity, or set identity by id, AuthenticateSoapClient performs necessary calls to the IIdentityCollection to reflect the current identity, the default identity and list of available identities.

This interface was designed to be mutable, but you shouldn't need to mutate it directly from your code.

public interface IIdentityCollection
{
    // returns a copy of identities stored within
    [NotNull] IReadOnlyList<Identity> List { get; }

    // gets or sets current identity
    Identity CurrentIdentity { [CanBeNull] get; [NotNull] set; }

    // gets default identity, can't set it here
    [CanBeNull] Identity DefaultIdentity { get; }

    // finds identity by id in a list of stored identities. if not found, returns null
    [CanBeNull] Identity FindById(Guid id);

    // indicates, whether there any identities stored within
    bool HasIdentities { get; }

    // clears the inner identity list, and populates it from "identities" parameter
    void PopulateFrom([NotNull] Identity[] identities);
}

All of these are designed to be testable and extensible. For example, SessionInfo constructor allows you to specify your own implementation of both ICredentials and IIdentityCollection.

public class SessionInfo : ISessionInfo
{
    public SessionInfo([NotNull] string sessionId, 
                       [NotNull] ICredentials credentials, 
                       [NotNull] IIdentityCollection identityCollection)
    {
        SessionId = sessionId ?? throw new ArgumentNullException(nameof(sessionId));
        Credentials = credentials ?? throw new ArgumentNullException(nameof(credentials));
        Identities = identityCollection ?? throw new ArgumentNullException(nameof(identityCollection));
        CreatedOn = DateTime.UtcNow;
    }

    // ... omitted for brevity
}

Examples

Generally, the best way to discover a library is to see it's unit-tests. However, some examples will be provided in this readme.

Authentication

using System;
using System.Threading.Tasks;
using MappedTfsoApi.Common.Facade;
using MappedTfsoApi.References.Authenticate;

namespace YourGreatApplication
{
    public class SomeClass
    {
        public Task<ISessionInfo> AuthenticationExample()
        {
            var factory = new TfsoApiFactory();
            var auth = factory.AuthenticateService();
            return auth.AuthenticateAndGetSessionInfoAsync(new Credential
            {
                ApplicationId = Guid.Parse("<your application key>"),
                Username = "<your login>",
                Password = "<your password>"
            });
        }
    }
}

Running this code and examining ISessionInfo object will yield following results:

{
  "SessionId": "<your session id>",
  "Credentials": {
    "IsEmpty": false,
    "Login": "<your login>",
    "Password": "<your password>"
  },
  "Identities": {
    "List": [
      list of identities
    ],
    "CurrentIdentity": {
      current identity, if any
    },
    "DefaultIdentity": {
      default identity, if any
    },
    "HasIdentities": true (or false, depending on whether there are any identities)
  },
  "CreatedOn": "UTC timestamp of session creation time"
}

Notes

This library is still in it's early stages, so any contributions/bug reports/feature requests are welcome!