Registering a Custom Widget in ArcGIS Enterprise 11.X
I have been asked on multiple occasions for help with registering a custom widget in ArcGIS Enterprise. My answer has always been, "I don't know. My Enterprise is still on 10.9.1." Well, that is changing. We are upgrading to Enterprise 11.3 and now that our testing portal has crossed the threshold into that magic 11.X world that allows for hosting custom widgets, I have hosted some widgets. So, I'm going to walk you through the process and what I learned along the way.
The first thing I did was pull up the official documentation, which was rather good in this case. Ordinarily, I'd drop a link here, but the document is imbedded within Enterprise itself on an internal server. I found it by opening Experience Builder, scrolling down the Insert Widget Pane and hitting the question mark next to Custom. Also, note that the box with the lines on it will take you to the Item Page on your Portal, so if you want to make your own documentation for your custom widget, that would be the way to find it. Nice touch, ESRI.
So we have our recipe, what's on the ingredient list?
- ArcGIS Enterprise 11.0 or higher
- Administrator privileges on your ArcGIS Enterprise
- A web server
- A custom widget
- Experience Builder Developer Edition
- Love (I mean it's not specifically needed for this procedure, but everyone needs love, even if they are too big and brave to admit it. If you are feeling low on your love supply lately, don't be afraid to reach out to someone. More people genuinely care about you than you even know.)
Step One: Prepare Your Server
I'm copying in steps 1-4 on the official guide and chances are, you won't have to do them.
1. Enable anonymous access to the virtual directory that is hosting your widgets.
The hosting location must be anonymously accessible.
2. Enable HTTPS.
Enable HTTPS access in your web server to avoid creating mixed content. Experience Builder does not allow mixed active content caused by loading HTTP under an HTTPS connection. In addition, your server should have a valid SSL certificate issued by a certificate authority to establish the HTTPS connection.
3. Enable Cross-Origin Resource Sharing (CORS).
Experience Builder runs under your portal domain, which may be different from the domain of the web server hosting your custom widget. You need to enable CORS in the web server so that access from your portal domain is allowed.
4. Add a JSON handler to your web server.
Each widget consists of a JSON manifest file that describes widget properties. Some web servers do not recognize the JSON file extension by default. In such cases, you need to add it to your server as a new MIME type at the application level or a higher level. The MIME type should have .json as the file extension and application/json as the MIME type.
At this point, I would like to remind everyone, I am not an Administrator. I'm also way dumber than I appear. I'm just a monkey who's really good at knowing which buttons give me bananas and which ones give me electric shocks. I don't know how to get your server set up if it's not done already. But chances are you, or whoever set up your server, already did all of these things, so you can probably start at the next step and if it doesn't work you will need to change something on your server.
Step Two: Compile Your Widget
This is the step in the process that is probably where most people slip up. Here's a truth that might be hard to swallow, that code you wrote that you worked so hard on, will never actually be used by your final application. The code in the your-extensions/widgets folder runs through a compiler converting it from TypeScript and React into pure JavaScript. It is also minified. This is the actual code your application runs and this is the code you will need to host your widget. So, even if you are just downloading a completed widget from the Custom Widgets Group, you will still need to put it through Developer Edition first.
The other way compiling can go wrong is a version mismatch. Each version of ArcGIS Enterprise has a corresponding version of Developer Edition. For ArcGIS Enterprise 11.3, the corresponding Developer Edition version is 1.14. Experience Builder can run widgets written in earlier versions, but it can't handle widgets from a newer version. And this limitation also matters for what version it is compiled in. So if you have a widget that was written in 1.12 but compiled in 1.15, it will almost certainly fail in Enterprise 11.3, but if you use 1.14 as a compiler, it should work.
Ok, that's what not to do. What to do? There are two ways to get the compiled version. If you've already built a project and hit Publish since putting the widget in your-extensions. It should already be compiled. (Not sure if you need to use the widget in your project, but I don't think so.) If your widget isn't already waiting for you in the client/dist-prod/widgets folder, stop your Client server and run npm run build:prod on that directory.
Step Three: Deploy Your Widget
Go to ...fileStructure/client/dist-prod/widgets in Windows Explorer and copy the folder containing your widget. Paste that folder onto your web server. Get the full URL to the manifest.json inside that folder. Open up your Enterprise Portal and go to the Content Tab. Click on Add Item and choose An Application, then Experience Builder Widget. Here is where you should enter that URL to the manifest.json. Finish completing the Add Item Wizard. You don't need me to tell you how to do that, do you?
Now, you'll want to Share it with your co-workers. And I encountered something odd on this step. The first time, I hit the big blue Share Button at the top of the Item Page. For some reason, this duplicated my widget both within My Content and Experience Builder. One version was Private and the other was shared with the Organization. On my other widget uploads, I used the Share Edit Button further down the page and didn't get a duplicate. So use the little button, not the big button.
Open up Experience Builder and say hi to your new widget, ready for your whole organization to enjoy.
