Building Your First Application

In this article

    Creating an application for the SuperOffice Online App Store is not something to take lightly. There are several key elements that all application vendors must understand before their creations are released into the wild.

    This article will guide you through the journey for successfully creating an application ready for SuperOffice CRM Online.

    Prerequisites

    You must have already:

    1. received a customer instance in SuperOffice Online Development (SOD) environment. Register as a CRM Online developer to receive your first customer instance.
    2. registered your application by completing this form to register your app or custom app
    3. build and host a page that receives JWT tokens, this web page must reside at your the Redirect URL you specified when registering your application.
    4. received your application Id and token. 

    The Journey Begins

    Building integrations for online is not the same as an onsite environment. Security is paramount, configuration is key, and there are some limitations to be aware of. 

    Before the journey begins, even before you attempt a first try at authenticating with SuperOffice Online, you must meet the following requirement:

    Requirements both Standard and Custom Applications

    You must have a running application at a specified Redirect URL that is able to process a request containing one or more security tokens. Supported security token formats is JWT. 

    If you do not meet this requirement, do that now. This must be done before your first attempt at authentication.

    Redirect URLs

    SuperOffice Online applications may provide more than one redirect URL. When necessary, specify all additional redirect URLs in the application registration form to add all secondary URLs to your applications Redirect URL whitelist. Do try to limit it to less than two, otherwise consider submitting a URL that incorporates a regular expression.

    To override the default redirect URL, specify the redirect_url query string parameter with one of your whitelisted urls.

    Example:

    OLD FORM (do not use anymore):

    http://sod.superoffice.com/login/?app_id=YOUR-APP-ID&redirect_url=YOUR-REDIRECT-URL

    OAUTH2 (preferred): 

    https://sod.superoffice.com/login/common/oauth/authorize?response_type=id_token token
    &client_id=YOUR-APP-ID&redirect_uri=YOUR-REDIRECT-URL&scope=openid&state=12345
    &nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7

    The difference of use between OLD FORM and OAuth2 URLs is the HTTP Response sent to the Redirect URL.

    The OLD URL request receives a JWT or SAML token in the body of the response with claims, including a Ticket credential.

    The OAuth2 URL request, which is an Implicit Flow request, returns a URL fragment containing an id_token, with tentant and user claims, plus an access_token credential. See the SuperOffice OpenID Connect article for more details.

    OAuth2 Native Apps

    With regards to OAuth2 Native App applications (desktop & mobile), a standard redirect URL must be used. In SuperOffice Online, app OAuth2 Native Apps Redirect URL will be set to some variant to the following:

    ^http://127.0.0.1\:\d{4,10}/desktop-callback$. 

    This means if your application must use the loopback IP address with any valid port number. The text desktop-callback must be specified when registering the application.

    Documentation

    As with any journey you need a map, and documentation is what will keep you on the road to success.

    SuperOffice CRM Online is identical to the SuperOffice CRM on premises web application, and both rely exclusively on NetServer web services to function. If you already know how to connect to and exchange data using NetServer web services, you are well on your way to knowing how to build applications for SuperOffice CRM online.

    If not, learn more about NetServer web services by reading the online web service documentation.

    All extensibility capabilities, what an application can do, are outlined in the SuperOffice administrative documentation. This comes in two forms:

    1. Technical Documentation
    2. Administration Documentation

    This means that anything a consultant can do inside the SuperOffice Admin application, any application can programmatically do the same thing during or after provisioning. This includes, but is not limited to; creating list items, user defined fields, web panels, sale guides, project guides, and creating preferences. 

    In addition to the online documentation, the samples include code examples that demonstrate most of these capabilities.

    Security

    The hardest part with online development is security, and security in SuperOffice Online environment is paramount. It might have once seemed odd to defer asking users for credentials by forwarding them off to another web site, but in todays online landscape where federated authentication is wide-spread, parters must get used to not asking users for their passwords. 

    Parters building application for online must be confortable with federated authentication, and all applications must use SuperID for authenticating users. The best place to get better aquainted with SuperOffice online security is by reading the Security and Authentication article.

    Application Models

    SuperOffice CRM Online supports two application models which represent how customers will interact with applications, internal, external and hybrid.

    The internal model is any integration that has a presence inside the SuperOffice user interface (UI). This means any application that adds a navigator button, menu button or a web panel is referred to as an internal application.

    The external model is any integration where most, if not all, interactions occur on a partner web site, or cloud service. This means any application that has no UI presence inside SuperOffice, and requires the user to navigate to a partner web site to use the application or service.

    The hybrid model is any integration that has a presence inside the SuperOffice UI and hosts some functionality on a partner web site, or cloud service. This is likely to be the most common type of application.

    Online applications have full access to SuperOffice NetServer web services and can live inside or outside of the SuperOffice user interface.

    Authentication Models

    There are type types of authentication models supported in SuperOffice CRM Online.

    Application User

    The typical application scenario consists of a user, signed into SuperOffice, who uses functionality provided by an internal application. The application, assuming it is hosted in a web panel, must at some point authenticate the user via SuperID to establish a local user session on the applications server, then use the token returned by SuperID for each successive call to the users web service endpoints. A signed in user context lasts for the duration of the session and is available as long as the user is signed in.

    Application System User

    A system user context is available anytime but has a limited duration. System user credentials are obtained by exchanging a system user token string for a system user ticket. The ticket can then be used for credentials. System user level credentials has unlimited access to the tenant and is not restricted by functional or data rights. The system user token string will not change and remains the same for the lifetime of the application.

    Environments

    New applications must start their life inside the SuperOffice Online Development environment (SOD). When a partner is satified their application is ready to be published in the App Store, SuperOffice will then migrate their application to Stage for testing and verification. 

    The stage environment is used primarily for testing and verifying an application prior to promoting to production and publishing in the App Store. In stage, an application must prove it can withstand a high degree of traffic without impacting the server, main website and additional applications that are running on the same server.

    The production environment is where SuperOffice Online and all published applications reside. 

    To learn more about building and deploying applications in the different envionments, please read SuperOffice Application Environments.

    Limitations

    There are some limitations when compared to on premises installations. Online applications are much stricter, and have a subset of capabilities when compared to an on-site SuperOffice web client application. With an on-site web installation, there is one web server hosting one SuperOffice web application site, and the owners can do what ever they with their installation.

    Often, customers like to have custom dialogs, custom archive tabs populated by custom archive providers that show information in new ways. While this is still possible with web panels in online customer installations, customizations that require placing files on the web server to augment the application are not allowed in the online environment.

    Custom dialogs require new config files on the servers file system, and custom archive providers require compiled dll's placed on the file system together with the web site. SuperOffice online simply does not allow any custom files in an online tenant site.

    Common on-site API customization examples not possible in CRM Online include, but are not limited to, the following:

    1. Archive providers
    2. Document Plug-ins
    3. Sentry Plug-ins.

    While this is not a complete list, please read the article Online Versus Onsite Extensibility to see a complete write up on this topic.

    This policy decision is related to security reasons, and SuperOffice is not willing to compromise tenant security.

    SuperOffice will continue to invest in research and development that in the future will be able to deliver equivalent onsite customization capabilities to SuperOffice CRM Online, however, a timeline for this is not available.

    Conclusion

    This page has discussed documenation, security, application models, authentication models, different environment, and some of the limitations with building online application. Read more about the specific areas by following the links, or navigating the menu on the left. 

    If you have any questions, please contact us and we will respond as soon as possible.