Coming soon: Your brand new Help Center & Community! Get a sneak-peek here

Getting started with SuperOffice API

Hey together,

first - if this is the wrong place in the forum for this question, please move it to the correct topic!

 

I'm trying to migrate an old SO Server Tool to SO Online, but I'm not sure, how I can achieve this now with one of the authentication workflows and APIs. Since I'm new to SO, this is very overwhelming for me - I already read a lot of tutorials/forum entries/etc. - but the more I read about it, the more confusion becomes. Not because it's not good documented, more because of the power of the API a developer obtains.

The best option would be to use the same implementation as before.

A short overview about the application:

  • Console application written in C# with .NET Framework 4.7.2
  • Used the packages
    • SuperOffice.NetServer.Core
    • SuperOffice.NetServer.Services
  • Authentication with username + password

The task of the tool is to convert contact data entries (and extended information, like telephone number) to a .csv file automatically once a day. We use it to migrate these data to our main telephone system. We created a "Selection" in the SO Web UI to query it. Furthermore, we used the ArchiveAgent with the ArchiveRestrictionInfo to obtain the data from the Selection, like this code example shows:

_mySession = SoSession.Authenticate(_user, _password);

//Initializing an Archive Agent
using (ArchiveAgent newArcAgt = new ArchiveAgent())
{
    //Get the dynamic selection with the ID = 136
    ArchiveRestrictionInfo[] archiveRest = new ArchiveRestrictionInfo[1];
    archiveRest[0] = new ArchiveRestrictionInfo("selectionId", "=", 136);

    // Get a page of results for an archive list, explicitly specifying the restrictions, orderby and chosen columns
    ArchiveListItem[] arcLstItm = newArcAgt.GetArchiveListByColumns(
    "ContactSelection", _archiveColumns, new ArchiveOrderByInfo[0],
    archiveRest, null, page, int.MaxValue); //MaxValue = Display all content on page 0

    if ("[I:136]" == archiveRest[0].ScalarValue) //Check if the correct Selection have been found
    {
        _logger.Info("Selection has been found! 'Alle Personen für Starface'");
        foreach (ArchiveListItem archiveRow in arcLstItm)
        {
            foreach (ArchiveColumnData archiveCell in archiveRow.ColumnData.Values) //Read all the ID's from the persons
            {
                string temporaryPersonId = archiveCell.DisplayValue.Replace("[I:", "").Replace("]", ""); //Split the ID from the brackets [ID]
                int personId = Convert.ToInt32(temporaryPersonId);
                _allPersonIds.Add(personId);
                _logger.Debug("GetIDs; PersonId Added; " + personId);
            }
        }
    }
    else
    {
        _logger.Error("Selection couldn't be found -- 'Alle Personen für Starface'");
    }
}

 

Now, the authentication needs to be done by another workflow when using SO Online - this is what I need to adapt to get the tool running again.

But how can I achieve this?

  • Is it even possible to authenticate my tool without redirecting to a federation gateway since it won't be executed by a human user who can enter credentials? Is the SystemUser workflow the correct way for me? Like: Github SuperOffice.DevNet.Online
    • If yes, what is the "ContextIdentifier" and "SystemUserToken"?

I have already registered as developer and also added my application (I'm not sure, if I have correct register it, since I don't know the different use cases for authentication). I got the application ID, the client secret and the apps private key for system user token signing. Furthermore, I also got access to a test tenant.

 

Can you please give some advices, to get the authentication work? It's "only" the authentication which is missing here. Maybe I'm on the correct way with the System User workflow? 

Thanks a lot and best wishes!

RE: Getting started with SuperOffice API

Hi Roland, welcome to the SuperOffice developer community! 🧑‍💻

Yes, it can be daunting to get started as there are several integration points. Even for migrating an app from onsite to online can be intimidating. 

I can confirm that you have so far successfully followed the steps to:

  1. Register an online developer account
  2. Register an online application

We have so far:

  1. Registered your online developer account in SOD environment  Everyone must start here before allowed in production.
  2. Registered your online application in SOD environment 
  3. Sent you your application details (via SendSafely), which you have downloaded and should have available.
    This download included:
    1. Application ID (client_id)
    2. Application secret (client_secret)
    3. Private certificate (used for conducting background processing with the propietary System User flow (hopefully one day we will instead support OAuth Client Credentials))

Yes, that referenced console application is 1 of 3 possibilities to correctly go about obtaining the system user credentials (system user ticket) needed for performing background processing. However, like all online services, you (the tenant administrator) must allow the application to access it's resources (i.e. web service endpoints).

You must do this step to create an Authorization Record in our operations center that permits the application to access the tenants resources, and you must do this step to get back (in the redirect URI) the System User Token for later use.

You can do this a couple different ways:

  1. Use our helper application to perform the login sequence to create the Authorization Record in our operations center and get the System User Token on the user account page (see the app description for details).
  2. Code your application in such a way that allows an interactive login own application to perform the login sequence to get the system user token as a claim in the JWT token returned to the redirect URI after successfully signing in the CRM Online login page.

The other 2 out of 3 options to obtain a system user credential is to:

  1. Use our newly published nuget package: SuperOffice.WebApi (in preview ATM). There are Samples on Github, read the System User section in the README.md file for usage instructions. We tried to make it as easy as possible.
  2. Create your own library to exchange the system user token for a system user ticket

Hope this helps!

 

 

Von: Tony Yates 25. Mrz 2021

RE: Getting started with SuperOffice API

Hey Tony! 

First of all - thanks for that fast answer! 

I will take a closer look into the steps/advices you described - and write back, if I'm struggling. Or even better, for reporting success :-) But I'm glad I was on the right track..

Thanks a lot!!

 

Von: Roland Spycher 25. Mrz 2021

RE: Getting started with SuperOffice API

Hello Roland, there are a myriad of other options here as well if you need more options.

You could use Database Mirroring to set up a synchronized SQL database on your local server, and just use plain SQL against it. 

You could also use CRMScript to create a CSV file that you can download from a URL in SuperOffice whenever you need it.

Von: Frode Lillerud 25. Mrz 2021

RE: Getting started with SuperOffice API

Hi, Roland

I might just be picking up on the wrong keywords.

But if you are describing data from SuperOffice Online, that needs to be delivered to a csv file for another system to pick up.

That makes me think about the possibilities DataBridge has with an export profile.

Create a new export - DataBridge - InfoBridge Knowledge Base (atlassian.net)

DataBridge product information (infobridgeuniverse.com)

I do not know how you need to manipulate the data, so my suggestion could be off.

Anyway, as Frode says, there are probably several ways to accomplish this.

 

 

Von: Filip Witzell 26. Mrz 2021

RE: Getting started with SuperOffice API

Hey Tony,

thanks a lot for your assist, I got it to work :-) 

I used the mentioned console application (https://github.com/SuperOffice/SuperOffice.DevNet.Online/tree/master/Source/SuperOffice.DevNet.Online.SystemUser.ServiceConsole) since its matched perfect for my purpose! 

At first, I used the https://devnet-tokens.azurewebsites.net/ website to get familiarized with all the different keys, tokens, certificates, etc. . Then I mapped it to my application to create/sign the System User Token and to obtain the System User ticket. The best of all, I didn't need to change the logic of the old application, only the authentication routine has changed - very good!

I'm now able to get my Selection as I wanted.

Thanks also to the other guys trying to suggest me some solutions. I think the case is now closed!

Now, next step is to get the application checked by SO, so I can run it on production (custom app, not necessary to publish it in the app store):

1. https://community.superoffice.com/en/developer/create-apps/resources/start-application-validation/

2. https://community.superoffice.com/en/developer/create-apps/resources/activate-custom-application/

(Somehow the links are currently not working correct, I hope this will change in the next days)

 

Thank you very much Tony! Have a nice day and stay healthy :-)

Von: Roland Spycher 6. Apr 2021