With GreenTools for Microsoft Apps (G4MS) v9.00 and up you are now able to complete service registration for accounts using ILE functions instead of the G4MSREGSVC command.  This is useful for shops that have custom screens or are web based only, and don't have the option of running commands from a command line.  This is similar to the changes made to GreenTools for Google Apps (G4G) recently.

We have also set up a RESTful API endpoint that allows you to send us your unique state code and a URL that you would like our site to redirect to when registration is complete.  

The new functions are used as follows:

g4ms_getRegistrationURL() - Retrieve the Microsoft Registration URL

// get a unique Code and URL 
g4ms_setValue('id':'bvstone@outlook.com');                            
g4ms_setValue('service':'*ONEDRIVE365');
rc = g4ms_getRegistrationURL(outStateCode:outURL:errMsg);     

Once this is called, the g4ms_getRegistrationURL function will return two very important pieces of information:

1. The outStateCode - This will be a unique ID that you will need to use to retrieve your token once the user has competed the registration process with Microsoft.  This code will also be used for URL redirection should you require that.
2. outURL - This is a direct link URL to Microsoft where the user will sign into their Microsoft Account and authorize G4MS to the required scopes and permissions.  You can either display this as a link for the user to click, or direct them automatically (in the case that this is a web application). 
   
   Because of the callbacks required for OAuth 2.0, once the user accepts the permissions from Microsoft they will be redirected back to a web page at BVSTools with instructions on how to complete the process. 
   
   OPTIONAL: If you would like them to be redirected to a site of your choosing, this can also be accomplished by calling a RESTful API we have set up.  Contact us for the endpoint to use.  The data will be JSON data and formatted as follows:

   {
        "state_code":"C4XPgffaaCNV2BiROAJMG2xx",
        "redirect_url":"https://www.yourpath.com/endpoint?field1=data1&field2=data2..."
   }

   The state_code value will be the code returned in the outStateCode output paramter of the g4ms_getRegistrationURL() function.  The redirect_url value will be where you would like the user redirected to once things are complete.  This can contain any information you wish returned to your endpoint.  If you are passing data as a query string, it is best that the data is URL encoded, especially if it contains any special characters.
   
   An example using GETURI to set up this redirect URL would be similar to the following:

   // build JSON into stream file or variable using YAJL, or a string, etc.
   jsonData = '{"state_code":"' + %trim(outStateCode) + '",' + 
              '"redirect_url":"https://www.yourpath.com/endpoint?field1=data1&field2=data2..."}';
   
   geturi_resetValues();
   geturi_setValue('gi_uri':'[contact us for endpoint]');
   geturi_setValue('gi_port':'443');  
   geturi_setValue('gi_ssl':'*YES');
   geturi_setValue('gi_reqmeth':'POST');
   geturi_setValue('gi_conttype':'application/json');
   geturi_setValue('gi_data':jsonData);
   geturi_setValue('gi_sprhead':'*YES');
   geturi_setValue('gi_outtype':'*RETURN');
   
   rc = geturi_call(GetUri_Out:GetUri_Head:GetUri_MsgCd:GetUri_Msg:errMsg);
   response = geturi_getResponseCode();  //ie 500, 200, etc
   
   //load into YAJL example 
   docNode = yajl_buf_load_tree(%addr(GetUri_Out:*DATA):         
                                %len(GetUri_Out):yajl_errMsg);   
   
   

   A content-type of application/json is required as well as properly formatted JSON.
   
   This call will return JSON and either success or error as follows:
   
   Success:

   {
     "response":"success",
     "state_code":"[the state code you passed in]"
   }

   Error:

   {
     "response":"error",
     "error":"reason for error"
   }

    

g4ms_exchangeCodeForToken() - Exchange Your Code for a Token and Set Up User/Service in G4MS

After the user has completed the accepting permissions required for G4MS through Microsoft, you now need to retrieve the OAuth 2.0 token (as well as other information) so it can be placed in the setup files inside G4MS.

// exchange the code for a token and set up in G4MS                                                                   
g4ms_setValue('id':'bvstone@outlook.com');                            
g4ms_setValue('service':'*ONEDRIVE365');                                  
g4ms_setValue('state_code':outStateCode);                                                          
rc = g4ms_exchangeCodeForToken(errMsg);                

As shown, we are sending the account information, the service and the outStateCode returned from g4ms_getRegistrationURL() to the gmsg_exchangeCodeForToken() function.  This will take the state code (which is NOT the same as the OAuth 2.0 code returned from Microsoft), make a web service call to get the OAuth 2.0 code, then call a Microsoft API to exchange that code for a token, refresh token, and other information.  The user will then be set up in G4MS and as long as the account is active, refreshing the token will be taken care of automatically by G4MS when calling any of the functions inside of the G4MS Addon Libraries.

See the GreenTools for Microsoft Apps (G4MS) documentation for a full set of instructions and settable variables for each of these new functions.

As always, please contact us with any questions.