GoParagon.Connector.Client 1.3.0

Connector .NET Client Library

Welcome to the Connector .NET Client Library! This library is designed to simplify the integration with various platforms such as QuickBooks Online, Microsoft Graph, G Suite, and more. By using the Connector app, you can access and manage data from these platforms through a unified API.

Overview

Connector is an app that facilitates seamless integration with multiple platforms. It allows you to:

• Connect to various platforms like QuickBooks Online, Microsoft Graph, G Suite, and others.
• Retrieve and manage data from these platforms through a single set of APIs.
• Simplify the process of obtaining and using data from multiple sources in your applications.

The Connector .NET Client Library is a NuGet package that provides developers with easy access to the Connector's APIs. With this library, you can quickly integrate the Connector's functionality into your .NET applications.

Features

• Unified API Access: Interact with multiple platforms using a single, consistent API.
• Easy Authentication: Simplify the process of authenticating and connecting to various services using API-KEY.
• Data Management: Retrieve, manipulate, and manage data from different platforms effortlessly.
• Extensibility: Easily extend and customize the integration to fit your specific needs.

Getting started

To get started using the Connector client, you will:

• Need to have an API-KEY. SignUpUserAsync returns it (see Paradigm ERP Integration), or a Connector administrator issues one for you. The Connector website only shows whether a key is set, so store it.
• Need to have at least one connect (QuickBook online, Microsoft, etc ...) to use their APIs

After you install the nuget package and get the API-KEY, you can use it.

using Connector.Client;
using Connector.Client.ApiService;

var connection = ConnectionBuilder.Create()
    .WithEndpoint("https://portalapi.para-apps.com")
    .WithApiKey("YOUR-API-KEY")
    .Build();

var customerService = new QuickBookCustomerService(connection);

var customers = await customerService.QueryAsync("select * from customer");

Paradigm ERP Integration

The Connector .NET Client Library now includes specific functionality for integrating with Paradigm ERP. With this feature, you can easily register users, generate access URLs, retrieve user information, and log users out from the Paradigm ERP platform.

User Registration and Access URL Generation

Step 1: User Registration with SignUpUserAsync

To register a user for the first time:

1. Create a connection using the ParadigmApiKey.
2. Create an instance of ParadigmErpService using the connection.
3. Use the SignUpUserAsync method to register the, specifying their email, provider, username, and company name. The method will return a URL directing the user to the Connector’s web interface.

var connectionForParadigm = ConnectionBuilder.Create()
    .WithEndpoint("https://portalapi.para-apps.com")
    .WithParadigmApiKey("PARADIGM_API_KEY")
    .Build();

var paradigmErpService = new ParadigmErpService(connectionForParadigm);

var response = await paradigmErpService.SignUpUserAsync(
    "test@gmail.com", 
    "Google", 
    "Your Username", 
    "Your Company Name"
);
Console.WriteLine(response.Url); // URL directing to the web interface

If you want to specify which connects to show on web interface, you can use the SignUpUserAsync method with the connects parameter:

var result = await paradigmErpService.SignUpUserAsync("test@gmail.com", "Google", "Bob", "Your company name");

Available connects are: Google, GoogleExtended, Microsoft, MicrosoftExtended, MicrosoftShared, QuickBook, HubSpotParadigm.

For Microsoft 365 shared mailboxes, see Shared mailboxes (MicrosoftShared).

The SignUpUserAsync method will return an object with:

• Url: Directs the user to the Connector’s web interface for further setup.
• ApiKey: The API key for the registered user, allowing API access.
• IsSuccess and ErrorMessage: check IsSuccess first; when it is false, ErrorMessage says why.

Save the ApiKey from the first call; the API does not give it out again. Calling SignUpUserAsync again for the same username and company returns IsSuccess: false with "This Paradigm user is already signed up." Older accounts still get their key back for now, but don't rely on it: that will be removed. If the key is lost, an administrator must issue a new one.

Step 2: Access URL Generation with GeneratePortalAccessUrlAsync

If you need to generate an access URL again:

1. Create a new connection using the ApiKey from the SignUpUserAsync response.
2. Create an instance of ParadigmErpService with the ApiKey-based connection.
3. Use GeneratePortalAccessUrlAsync to retrieve the access URL.

var connection = ConnectionBuilder.Create()
    .WithEndpoint("https://portalapi.para-apps.com")
    .WithApiKey(response.ApiKey) // the ApiKey from the SignUpUserAsync response
    .Build();

var erpService = new ParadigmErpService(connection);

var response = await erpService.GeneratePortalAccessUrlAsync("Microsoft"); // the connect to open
Console.WriteLine(response.Url); // Access URL for the web interface

The GeneratePortalAccessUrlAsync method will provide an Url that can be used to access the Connector platform again. This is useful for re-establishing access without needing to re-register the user.

Step 3: Retrieve User Information with GetUserInfoAsync

To get detailed user information:

1. Use the same connection created with the ParadigmApiKey.
2. Use the GetUserInfoAsync method, providing the API key and connect name.

var connection = ConnectionBuilder.Create()
    .WithEndpoint("https://portalapi.para-apps.com")
    .WithParadigmApiKey("PARADIGM_API_KEY")
    .Build();

var userInfoResponse = await new ParadigmErpService(connection)
    .GetUserInfoAsync(
        response.ApiKey, 
        "Microsoft"
    );

Console.WriteLine(userInfoResponse);

Step 4: Logout User with LogoutUserAsync

To log a user out from a specific provider:

1. Create a connection using the ParadigmApiKey.
2. Use the LogoutUserAsync method, providing the API key and the provider name.

var connection = ConnectionBuilder.Create()
    .WithEndpoint("https://portalapi.para-apps.com")
    .WithParadigmApiKey("PARADIGM_API_KEY")
    .Build();

await new ParadigmErpService(connection)
    .LogoutUserAsync(
        response.ApiKey, 
        "Microsoft"
    );

Console.WriteLine("User successfully logged out.");

Shared mailboxes (MicrosoftShared)

MicrosoftShared includes everything in MicrosoftExtended (send and read mail, inbox forwarding) and adds Microsoft 365 shared mailboxes, such as support@company.com. Connector support turns forwarding on separately for the user's own inbox and for the shared mailboxes, so a user can forward one of them or both.

1. Send the user to set it up

Sign up with the MicrosoftShared connect and open the returned Url. The user signs in with Microsoft, then lands on a Shared mailboxes page and adds the addresses. Connector checks in Microsoft 365 that the account has Full Access before it saves an address.

var paradigmConnection = ConnectionBuilder.Create()
    .WithEndpoint("https://portalapi.para-apps.com")
    .WithParadigmApiKey("PARADIGM_API_KEY")
    .Build();

var signUp = await new ParadigmErpService(paradigmConnection)
    .SignUpUserAsync("bob@company.com", "MicrosoftShared", "Bob", "Your Company Name");

Console.WriteLine(signUp.Url); // open in the browser

2. Let the user change the list later

Unlike the other connects, MicrosoftShared can be opened again while the user is connected. Generate a new URL with the user's ApiKey; it signs them in and opens the Shared mailboxes page.

var userConnection = ConnectionBuilder.Create()
    .WithEndpoint("https://portalapi.para-apps.com")
    .WithApiKey(signUp.ApiKey)
    .Build();

var access = await new ParadigmErpService(userConnection)
    .GeneratePortalAccessUrlAsync("MicrosoftShared");

Console.WriteLine(access.Url);

3. Check the status, read the mailboxes, or disconnect

Use GetUserInfoAsync and LogoutUserAsync with "MicrosoftShared", as in steps 3 and 4 above.

• ConnectStatus is true when the user has any Microsoft connection. It doesn't confirm that shared mailboxes are set up.
• SharedMailboxes lists the addresses the user added, for example ["support@company.com"]. It is filled only when you pass "MicrosoftShared" and the user is connected with MicrosoftShared. Otherwise it is empty.
• The user can change the list at any time, so call GetUserInfoAsync again when you need the current list.
• SharedMailboxes is null when the Connector server is older than this package, so check for null.
• Logging out removes the Microsoft connection and all of the user's shared mailboxes.

var userInfo = await new ParadigmErpService(paradigmConnection)
    .GetUserInfoAsync(signUp.ApiKey, "MicrosoftShared");

foreach (var address in userInfo.SharedMailboxes ?? new List<string>())
    Console.WriteLine(address);

4. Send from a shared mailbox

Call SendEmail2Async with the user's ApiKey and set From to one of the addresses in SharedMailboxes. The customer sees the email from the shared address, and the copy is saved in the shared mailbox's Sent Items.

var internetMessageId = await new MicrosoftSendEmailService(userConnection)
    .SendEmail2Async(new SendMicrosoftEmailV2Command
    {
        From = "support@company.com",
        ToRecipients = new List<string> { "customer@example.org" },
        Subject = "Re: Order 1042",
        Body = "Thanks, it ships today.",
        IsBodyHtml = false
    });

• If the user has no Send As permission on the mailbox, the call fails with 400 and a message that names the mailbox.
• If the user connected before this feature, the call fails with 401 and a reconnect URL. Open it so the user consents to the new permissions.

What Paradigm receives

• Each new email is posted to the same api/Conversation/email endpoint as personal-inbox emails, with the same payload.
• There is no separate mailbox field. The shared address is usually in ToRecipients or CcRecipients.
• Only emails that arrive after a mailbox is added are forwarded. Emails already in the mailbox aren't copied.
• If one email reaches two connected mailboxes, Paradigm receives it once per mailbox, with the same InternetMessageID.

Requirements

• The signed-in Microsoft account needs Full Access to each shared mailbox in Exchange. New access can take up to 1 hour.
• To send from a shared mailbox, the account also needs Send As (or Send on Behalf) on that mailbox in Exchange. Only an admin can grant Send As.
• The connect asks for the Mail.Read.Shared, Mail.ReadWrite.Shared and Mail.Send.Shared permissions. On tenants that block user consent, an IT admin must approve the app once.
• Connector support must turn on shared mailbox forwarding for the client. It is separate from personal inbox forwarding.