Updating Portal Revision results in indefinite "pending" state

[Berbe]

Bug description

Using the shipped tools to download/upload content from/to the developer portal of an API Management instance, I ended with a split-brain situation o nsaid developer portal:

• Developer portal (https://<service name>.developer.azure-api.net/) entered in user/unauthenticated mode shows published content
• Developer portal (https://<service name>.developer.azure-api.net/) entered in administrative/authenticated/editing/WYSIWYG mode keeps showing the original, unmodified content, not the published one

I used the scripts.v3 tools, which leverage some Azure API Management REST API undocumented routes and the Blob service REST API to handle the underlying static content.

Using revisions I created from the different content sets, I am able to publish, through the Azure Portal Web GUI, either version of the content as I see fit, whose deployment is confirmed on the user view upon completion. The administrative view never vary.

Reproduction steps

1. Create a revision from the current developer portal content
2. Use scripts.v3 tools to download static content
3. Use scripts.v3 tools to upload and publish (new revision) content
4. Verify the user mode displayed published content
5. The administrative mode displays wrong (old) content
6. Roll back content to the first revision (Web GUI), and check user mode updates accordingly

Expected behavior

The user and administrative mode of the developer portal integrated within an API Management instance shall always display content deployed last (either uploaded or through revision change).

Is your portal managed or self-hosted?

Managed

API Management service name

Is not that a sensitive piece of information?

Environment

• Operating system: GNU/Linux Debian Buster
• Browser: Firefox 78.0.11esr, Chromium 90.0.4430.212, Firefox 89.0.1 (does not seem to be a client-side problem)

[msftbot[bot]]

@Berbe, thank you for opening this issue. We will triage it within the next few business days.

[mikebudzynski]

@Berbe, it's not expected and we need to go through the logs and your service configuration to figure out the issue. Could you open an Azure Support request?

[msftbot[bot]]

@Berbe, please, contact Azure Support for assistance and help in resolving your problem.

[Berbe]

@mikebudzynski I immediately forwarded your answer internally and a support case will be open in order to dig through instance logs.

In the meantime, I left the affected instance untouched and went on testing another one. It seems I hit the bug again, and while I am still unsure on what exactly caused it, I got more precise steps to share with you, in case they ring a bell. Here is what I did:

1. Created revision original (through Web GUI) based on original developer portal content : revision was automatically published; content from both user and administrative views adequate
2. Customised contents and published revision custom from it (through tools dealing with API Management + Blob storage REST APIs) : revision was automatically published; content from both user and administrative views adequate
3. Edited description of said (custom) revision through the Web GUI Revision's status transitioned indefinitely to Pending <- I guess that is when the bug stroke
4. Waited a long time (next work shift)
5. Published revision original (through Web GUI) which ended up reaching the Completed state. Revision custom was still stuck in the Pending phase. User view matched with contents from revision original, while administrative view showed contents from revision custom
6. Revision custom then transitioned to Completed without manual action, and got tagged current Contents shown on user and administrative views matched revision custom This is odd.
7. After having published revision original (though Web GUI), user view showed its contents, while the administrative view was still showing contents from custom

[mikebudzynski]

Thanks for the reproduction steps, @Berbe. Switching the portal revisions only changes the published (user view) portal. Content in the administrative mode will always be the latest, regardless of the published revision. There seems to be a bug in handling the revision updates, like changing the description - I was able to reproduce it.

[msftbot[bot]]

@Berbe, thank you for reporting the bug.

[Berbe]

The last steps are even more worrying, as they seem to permanently break the administrative view refresh from content upload or revisions switch. This was the main problem leading to my investigation and this bug report, which I see has been renamed.

Per my own tests, this is not recoverable, and renders the developer portal, in essence, unusable.

[mikebudzynski]

@Berbe, I am not sure if I understand your point.

The portal revisions apply only to the published portal's content. At this moment, we don't provide revisions for the administrative mode content, although it is something we've been exploring for the future. If you need to version the administrative mode content, we suggest that you:

1. Perform backups using the scripts
2. Always deploy developer portal changes in the production environment using CI/CD pipelines

[Berbe]

Because content needs to be edited/generated through the WYSIWYG tool part of the developer portal instance, content download/upload through scripts can only be used as a disaster recovery mechanism. The only way to externalise this WYSIWYG tool would be to self-host this portal. In the current state of things, I do not see how a user could generate contentItems, which use a complex templating system, manually.

Revisions can be very useful, allowing one to "freeze" a specific published version, allowing "safe" points to be identified during the portal lifetime. The problem is that without revisions, any publishing of currently edited content in administrative view or any content pushed through the tools will immediately and irrevocably overwrite current user view.

Worse, my understanding is that using the tools to upload content will also overwrite current administrative view, ie destroying content being potentially in the process of being edited. Am I right?

Revisions would allow to easily switch between version of the content and would act as the first level of recovery. If it fails (content from the API Management is critically lost), content upload could kick in. In case content up load is done with previous content already exist, identifying it with a specific revision would allow switching between that content and older releases, in case problems arise.

[elvirdolic]

We have one issue with publishing a new revision. We have a few revisions that are stuck in the pending state and we only see

If we access the public website. The Dev Portal to customize the Portal is working.

How to get out of it?

        {
              "id": "**redacted**",
            "type": "Microsoft.ApiManagement/service/portalRevisions",
            "name": "202205040706",
            "properties": {
                "description": "",
                "statusDetails": null,
                "status": "pending",
                "isCurrent": true,
                "createdDateTime": "2022-05-04T07:06:10.183Z",
                "updatedDateTime": "2022-05-04T07:06:10.183Z"
            }
        },
        {
            "id": "**redacted**",
            "type": "Microsoft.ApiManagement/service/portalRevisions",
            "name": "20220503130742",
            "properties": {
                "description": "Rest Api Update try",
                "statusDetails": null,
                "status": "pending",
                "isCurrent": true,
                "createdDateTime": "2022-05-04T08:11:46.283Z",
                "updatedDateTime": "2022-05-04T08:11:46.283Z"
            }
        },
        {
            "id": "**redacted**",
            "type": "Microsoft.ApiManagement/service/portalRevisions",
            "name": "20220503145932",
            "properties": {
                "description": null,
                "statusDetails": null,
                "status": "pending",
                "isCurrent": true,
                "createdDateTime": "2022-05-03T12:59:51.74Z",
                "updatedDateTime": "2022-05-04T08:16:11.467Z"
            }
        }