If you have already implemented Open Admin you have most likely created a _config folder on your site and placed the menu.json inside.
With the introduction of custom apps the Open Admin implementation has changed to follow a similar workflow to developing apps. This means that sites that already have Open Admin implementations will need to be adjusted to continue working. Here are the steps you need to take:
- The first step is to register your partner user as a developer and request an app key (username: alpha password: bcdevdocs). Open Admin implementations are considered as apps, so they need to be registered and packaged as apps.
- Once you have the developer user registered and the app key generated, create this folder: /_System/apps/[your app key]/_config
- Copy the menu.json file from the old _config folder located in the site's root to this new _config folder.
- You can delete the original _config folder located in the site root, it will no longer be used
To put it simply, the basics of the Open Admin have not changed at all. The only difference now is in order to use Open Admin you will need to register an app and place the menu.json file the app's folder.For example - if you are using Open Admin on 5 sites, each of them with a different menu.json file (each site has a different menu structure) all you need to do is:
- Register your user as a developer and request an app key
- Let's assume the app key we send back is "my-custom-menus-2"
- Create this folder on all 5 sites: /_System/apps/my-custom-menus-2/_config
- For each of your site copy the menu.json from the root of the site to the /_System/apps/my-custom-menus-2/_config folder
That's it, basically you have registered a single custom app, "installed" it on each of your sites, and use a different menu.json for each site.
Migrating existing apps to the new authorization model
In this section we will go over the adjustments needed for existing applications developed prior to the 12th November release.
If you already have an app deployed and working here is what you will need to do in order to ensure your app keeps working.
Register the app
One of the most important changes introduced is the concept of app and developer registration. Please register your user and obtain an application key for your existing applications using this form here.
Registering your partner user as a developer is an one-time process, however each application you have already developed or will develop in the future will need its own unique app key.
Warning: After receiving your app key double check to make sure the folder the app is stored in is identical to the app key you have received. Assuming your app is stored in the folder /_System/apps/dynamic-daily-scheduler but the app key isdynamic-daily-scheduler-1 you will need to rename the app's folder from dynamic-daily-scheduler to dynamic-daily-scheduler-1
Modifying the Open Admin menu.json
After getting your app key you will need to modify the app's menu.json file in order to make sure the OAuth authorization process is started and the access token is generated.
Here is how to modify your menu.json file, at the moment it most likely looks something like this:
{
"menu-my-first-app":{
"weight":100000,
"title":"Hello World",
"attr":{
"href":"/_System/apps/this-is-my-first-app/index.html"
}
}
}
Note: Do note that in this example the folder name the app is stored in is different the app key. You will need to rename the folder from this-is-my-first-app to my-first-app
What you need to change is the "href" parameter. Assuming your app key is "my-first-app" the menu.json file should become:
{
"menu-my-first-app":{
"weight":100000,
"title":"Hello World",
"attr":{
"href":"/Admin/AppLoader.aspx?client_id=my-first-app"
}
}
}
Modifying the authorization sequence
Apps built before the 12th November do not use OAuth for authorizating the API calls. Instead they use on the token stored in the Admin Console authentication cookie - siteAuthToken. With the new authorization mechanism, because the app runs in it's own sandboxed domain, you will no longer have access to any cookies set on the Admin console's domain. See this section for a more detailed explanation of the context apps run in.
As a result of the new authorization mechanism you will also need to change the way the token is read and stored.
Right after you change the OpenAdmin menu.json as described in the previous step the App Loader will generate the OAuth access token and pass it into the URL of the app's landing page.
Basically what you need to change is the way you get the access token, instead of getting it from the siteAuthToken cookie you now get it from the landing page's URL hash.
Simpler yet, you can use the bcapi.js SDK to have the access_token cookie set for you. Read a detailed overview of the OAuth authorization process.
Done!
At this point your existing apps should properly configured to use the new OAuth authorization method. Your partner user is registered as an app developer, you have app keys for your apps, the Open Admin config file (menu.json) is updated and triggers the OAuth authorization process and once the app is launched it stores the token provided for later use with API calls.
Comments