How does Smartdocs interact with Edge?

Not applicable

We use Smartdocs on our public site, and we find it to be an elegant, effective documentation system.

However, we are having difficulty understanding and dealing with the relationship between Edge and the portal elements of Smartdocs. We can see in the configuration that they communicate. We have learnt the hard way, for example, that if we delete a model on our Drupal test environment, it will break our Smartdocs live environment.

It would be helpful to know why Smartdocs needs Edge. How does Smartdocs interact with Edge? What elements involve Edge? Which changes to my Smartdocs environment cause a write to Edge, and are thus not-safe in my portal test environments? Please share your wisdom!

Solved Solved
2 9 1,156
1 ACCEPTED SOLUTION

Hi @tpearson - Apologies that we don't have more info about this in the docs. I'll add a section that better describes it. Here's the deal:

Models are stored at the org level. When you create a model in your portal, it's getting stored in the Edge management layer, and your portal then becomes an editing mechanism of that org-scoped model. The rendered Drupal nodes, and the admin view of the model in the portal, are continuously synchronized to the backend model. When you modify a method in your portal, the change gets written back to the model.

When you create a model in the portal, a unique internal name is generated for the model. That internal name also appears in the URL of the rendered SmartDocs.

Now let's talk different portal environments. Let's say you migrate a portal from dev to prod in Pantheon. Those two portal instances are pointing to the same model in Edge (assuming the internal model names are identical). It may look like two unique models (one in each portal), but they're referencing the same model. So when you delete a model from one environment, it deletes the model from Edge, which affects the model in the other portal environment.

If you want uniqe models per environment, make sure each model has a unique name.

Here's a curl call you can use to list all the models in your org:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

Hope that helps.

View solution in original post

9 REPLIES 9

Hi @tpearson - Apologies that we don't have more info about this in the docs. I'll add a section that better describes it. Here's the deal:

Models are stored at the org level. When you create a model in your portal, it's getting stored in the Edge management layer, and your portal then becomes an editing mechanism of that org-scoped model. The rendered Drupal nodes, and the admin view of the model in the portal, are continuously synchronized to the backend model. When you modify a method in your portal, the change gets written back to the model.

When you create a model in the portal, a unique internal name is generated for the model. That internal name also appears in the URL of the rendered SmartDocs.

Now let's talk different portal environments. Let's say you migrate a portal from dev to prod in Pantheon. Those two portal instances are pointing to the same model in Edge (assuming the internal model names are identical). It may look like two unique models (one in each portal), but they're referencing the same model. So when you delete a model from one environment, it deletes the model from Edge, which affects the model in the other portal environment.

If you want uniqe models per environment, make sure each model has a unique name.

Here's a curl call you can use to list all the models in your org:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

Hope that helps.

Thanks Floyd. Are the model specific handlebars templates also stored on Edge? If I modify my local handlebars templates in dev, will this affect my live model? And the global one too?

Looking into this...

Edge handles the rendering of SmartDocs HTML, which then gets picked up by the portal. In the same way that proxies and developers exist independently of environments, so do API models, so if you delete a model (or developer) from your dev portal, it is gone everywhere. I'm sure we can explain that better in the docs.

Under the hood, Edge can actually have multiple templates for each model, but the Portal simplifies that by offering the ability to set one default template for all models (Configuration > SmartDocs). While that default template is stored in Drupal, Drupal handles the complexity of applying it to every model you create.

If you want to experiment, in theory you could create a model that you render but don't publish. Then you could tweak that model's template in model > settings until you decided to update your default template.

Having checked with the team, I must slightly amend what I wrote earlier. The portal ships with a 'default-template' that it uses every time a model is created. Later, if you want to modify the template for a given model, from the model listing page click settings. Click "Save Template," will then update the template associated with that model in Edge.

Thanks, Marsh. Here's a diagram that illustrates the relationship between a model, portals, and templates. The org-scoped model is the source, and the portals provide the editing and rendering.

1606-smartdocs-model-diagram.png

FYI, I've added a new section to the topic that describes the architecture.

http://apigee.com/docs/developer-services/content/using-smartdocs-document-apis#models

I also added a "Deleting" section at the end of the topic that briefly describes the behavior.

@tpearson, apologies for the confusion, and thanks for raising this. FYI @Cushla O'Leary.,

@jonesfloyd

Sorry if the mode of the question is wrong but,

Unique model => Unique name, so this means that the content would be the same in all the three environments for the three models except their names,so if any modifications are to be done, then all the 3 models should be updated manually?? or is there any automation for this.

Thanks

Hi @sudha pidaparthi - If by "environments" you mean Apigee environments within an organization (multiple portals whose configuration points to the same model), then you would only need to modify the one, org-scoped SmartDocs model to have the content changes reflected in all portals that point to the model.

Note that there is some synchronization lag time between updates you make to a model when editing the portal's copy of the model in Drupal.

For example, let's say you have model "CoolAPI" in org "myOrg," and you have two Drupal portals (two different environments, say "test" and "prod") that are rendering "CoolAPI" (both portals point to "myOrg" in the SmartDocs configuration).

In the "test" portal, if you modify the content of a method in CoolAPI, that change will after a time be automatically written to the master model in myOrg, and the "prod" portal will then pick up the update when it automatically syncs with the model.

Note that you have to be careful when doing this. If there are changes you don't want to make public yet (which is why you'd be tempted to make the changes in "test"), updating CoolAPI in "test" also makes the changes in "prod" when both portals are using the same model.

Having multiple models that differ only by name does make them unique. So any changes you make to CoolAPI won't affect CoolAPI_2. So yes, you'd need to manually modify CoolAPI_2 in order to make the same change you made in CoolAPI. There's no type of auto-sync or include mechanism to keep identical-but-differently-named models in sync.

Hope this helps.