Manage Tenant Status Changes

In this article

    When a tenant installation undergoes changes, SuperOffice sends out a change notification to each approved application.

    As tenant installations experience state changes, each application vendor is able to receive a notifications about change events, and handle them if necessary. Notifications offers the ability to mitigate any potential errors that might occur when a tenant enters an unreachable state.

    Applications use notifications to ensure the application does not attempts to connect to that particular tenant when the tenant is unavailable. Then, the application is able to resume operations as normal when a notification is received that indicates the tenants availability has resumed.

    When SuperOffice upgrades a tenant, for example, SuperOffice looks at each application approved by the tenant, and sends out a notification to each one to indicate that the tenant is about to be upgraded. This provides the application an opportunity to know when a tenant going to be unavailable and why communications with that tenant cease until further notice.

    To receive notifications, application vendors must provide a State Change URL that specifies where SuperOffice sends notifications. For example:

    https://www.awesomeapp.com/NotifyCustomerStateChange

    The JSON payload contains the tenant context identifier, the change type, a text representation of the installation version, the version of the fileset and a JWT to verify it was sent by SuperOffice.

    {
      "ChangeType": 0,
      "ContextIdentifier": "Cust12345",
      "VersionName": "Release 8.4 R08",
      "FileVersion": "8.4.12.1234",
      "Token": "ejy234ASD...1234#"
    }

    The change type is a number value that that correspondes to the operation performed on the tenant. The possible change types are:

    0 Upgrade Occurs when a tenant installation is upgraded to a new version of SuperOffice
    1 BackupRestored Occurs when a tenant installation is restored from a backup.
    2 Suspend Occurs when a tenant installation is placed in suspension.
    3 Resume Occurs when a tenant installation is resumed from another operation.
    4 Delete Occurs when a tenant installation is deleted.

    Code Example

    While there are several ways to accomplish processing these notification, the following is a short description of what that might look using .NET and C#.

    CustomerStateChangeNotificationType Enumeration

    public enum CustomerStateChangeNotificationType
    {
        Upgrade = 0,
        BackupRestored = 1,
        Suspend = 2,
        Resume = 3,
        Delete = 4
    }

     

    Notification Message

    public class NotificationMessage 
    { 
        public CustomerStateChangeNotificationType ChangeType { get; set; } 
        public string ContextIdentifier { get; set; } 
        public string VersionName { get; set; } 
        public string FileVersion { get; set; } 
        public string Token { get; set; } 
    } 

     

    API Controller and JWT Validation

    public class NotifyCustomerStateChangeController : ApiController 
    { 
        public void Post([FromBody]NotificationMessage message) 
        { 
           try
           {
               // SuperIdTokenHandler is available in 
               // nuget package: SuperOffice.Crm.Online.Core
    
               SuperIdToken validated = ValidateToken(message.Token);
    
               // process accordingly...
               
    
           }
           catch (Exception ex)
           {
               // handle invalid token...
               throw;
           }
        } 
    
        public static SuperIdToken ValidateToken(string token)
        {
            var path = System.Web.Hosting.HostingEnvironment.MapPath("~/App_Data/") + "SOD_SuperOfficeFederatedLogin.crt";
    
            var tokenHandler = new SuperIdTokenHandler();
            tokenHandler.JwtIssuerSigningCertificate = new X509Certificate2(path);
            tokenHandler.CertificateValidator = X509CertificateValidator.ChainTrust;
            tokenHandler.ValidIssuer = "https://sod.superoffice.com";
            
            return tokenHandler.ValidateToken(token, TokenType.Jwt);
        }
    } 

     

    Conclusion

    It's important that application take advantage of these notifications to ensure their environments are kept up-to-date with the status of SuperOffice CRM Online tenants.

    Notifications ensure vendors are aware when that state of existing customers change, for example their SuperOffice subscription, as well as know when tenants are placed in unstable states that do not respond to on-going requests.