Maintenance mode via Swagger authentication

Maintenance Mode is only available to the host organization, and is accessible only via Orchestrator’s API.

In conclusion, you should switch the tenant to Host.

  • The Orchestrator interface is unavailable to everyone during maintenance.
  • You can now shut down IIS and proceed with any maintenance or update actions needed. Maintenance Mode will persist through any stop, restart, or upgrade operation until manually switched off.
  • Restart IIS and Orchestrator when all maintenance actions have been completed. Turn off Maintenance Mode using the /api/Maintenance/End endpoint. As outcomes:
    • All job executions scheduled to run during the maintenance mode are skipped;
    • A maintenance log is created for each tenant. The log summarizes all stopped/killed jobs and skipped trigger executions.

I know this operation. But my problem is that the Maintenance_End API returns 401 error as “You are not authenticated!”

Can you login to Host and then refresh the Swagger page for https://ORCHESTRATOR_HOSTNAME/swagger/index.html#/Maintenance/Maintenance_End ?

Can you get the Host JWT access_token in Postman?

I cannot log on to Orchestrator any more. Is there anyway from Swagger to authenticate again ? Or I have to try Postman ?

For Cloud Orchestrator, there is an “Authorize” button in Swagger for authentication. Is there similar way in Swagger for On-Premise Orchestrator ?

Try this approach:

  1. Open cmd.exe as Administrator and type iisreset

  2. Open IIS Manager → Application Pools to see if they are started

  1. Open IIS Manager → UiPath Orchestrator → check if the Website is started

  1. Open IIS Manager → Check if the server is started

No, in On-Premise Orchestrator Swagger, you should open a new tab and login into the needed tenant to have access in Swagger resources.

Thanks a lot for your steps. Unfortunately, after restarting IIS (your step 1), checked that all (under your step 2 -4) are started. I then tried to logon to Orchestrator, it is still not available under the Maintenance Mode (as below picture).

My first couple questions is

  1. What version of Orchestrator are you using?
  2. What authentication methods do you have enabled? Including if you’d disabled Basic authentication for any tenant.

Maintenance Mode was introduced in 2019, and in 2020 Identity Service was added.

When I test on my 2021 sandbox with a number of authentication methods enabled, I can reach Identity Service to authenticate by directly visiting <orchestratorhost>/identity as well as Swagger <orchestratorhost>/swagger while in Maintenance Mode.

(Basic on Host & Default Tenant, Windows Auth, Azure AD, and SAML on the Host, along with Azure AD on Default Tenant).

When I authenticate with Identity, it doesn’t seem to carry over other than the Windows Authentication, but unfortunately if I recall correctly Windows Auth can only authenticate to the Default Tenant, so it wouldn’t work in this case as you need to be authenticated to host.

In my case I happen to have 3 users configured for the HOST the original admin account and a couple accounts associated with domain users and I can use these to to authenticate against the /api/Account/Authenticate end point. Unfortunately here Swagger interface doesn’t expose a way to inject the Bearer Token and when hitting one of the /api/Maintenance/* endpoints the authentication challenge is received, but it doesn’t like any of the credential combinations I’ve tried.

So using Postman or another form of calling the API that allows you to manipulate the Requests will need to be used, just make sure that you are passing host as your Tenant when authenticating.

Some alternative methods if it suites you would be

PowerShell and UiPath.PowerShell Module and very basic usage would be below

If you’ve never used the Module before, you’ll likely need to Install NuGet PackageProvider along with Registering the Repository, more information can be found in the Readme of the Github Repository I linked to above.

Install-PackageProvider -Name NuGet -Force -Scope CurrentUser
Register-PSRepository -Name UiPath -SourceLocation
Import-Module UiPath.PowerShell -MaximumVersion
Get-UiPathAuthToken -URL https://orchestrator/ -TenantName host -Username admin -Session
Start-UiPathMaintenance -Phase Draining
Start-UiPathMaintenance -Phase Suspended

In the above I’m specifying the max version of the module to use as there is an issue with higher versions when still using Orchestrator 2019 and I haven’t validated compatibility for Orchestrator 2020 or 2021 yet.

Short of that if you are in a bind, you can go into the Database and modify the associated record in the dbo.MaintenanceSessions table by setting the State field to 0 and for consistency though logically not required in my testing setting the EndedAt.

The available State Enum as defined by the MaintenanceSettings model is 0=None, 1=Draining, 2=Suspended

1 Like

Many thanks and appreciate your detail instructions.

To answer your questions:

  • I am using Orchestrator 2022.4 (On-Premise) under Windows Server 2019
  • To use Maintenance Mode, I have logged on to host organization using admin account
  • In Swagger, I execute the Maintenance_Start api to send the Orchestrator to Pending stage. After a few hours, probably my authentication expired and cannot use this api anymore (error 401, "You are not authenticated!)
  • For Application Pool user, I have enabled Anonymous Authentication

Some update:

  • I closed all tabs in Chrome and reopen Chrome
  • I try to log on to /identity with host organization as admin, and was successful. I can even use Orchestrator Administration to add new user
  • I use another tab to go to /swagger, and execute the Maintenance_End api. Unfortunately it returned the same 401 error (You are not authenticated!"
  • I then try to use the same tab where Orchestrator host as admin was logged on, and change to /swagger, and execute the Maintenance_End api. Same error occurred.

Probably I will try the Postman approach, but seems that it needs some effort to setup the environment. Will update you on any results.


1 Like

Double check if the Orchestrator certificate is valid.

It is a self-sign certificate, and I have been successfully logged on to the host and tenant.

If I want to use Postman, do I need to import any UiPath collections before I can post the api ? There are quite a few out there, and which one should I use ?


You cannot use postman for that for long as I know.

You should use the Swagger endpoint


while you are connected to the host Orchestrator in another tab.

There is not enough. With that certificate, you should have the appropriate permissions to IIS_IUSRS and IIS APPPOOL\Identity

For the above go to Start → type certlm.msc → Certificates - Local Computer → Personal → Certificates → Find from the list the freshly created certificate → Select it → Right click on it → All Tasks → Manage Private keys… → Add as well in the users along with the application pool user IIS_IUSRS and IIS APPPOOL\Identity → then perform a iisreset in cmd.exe

Thank you Codemonkee and @marian.platonov

Eventually I make my Orchestrator alive by using Postman. Detail steps as below:

  • Use Swagger Account api to generate the token
  • Use Postman to pass the Maintenance Start and Maintenance End api with the token generated
  • In Postman no need to setup any environment or import any collection
  • Simply put the relevant info to the Endpoint, Parameters, Header, Body, and Authentication


1 Like

No problem!

I’ve never really used anybody’s existing Postman Collections for UiPath - generally define my own depend on what my needs are.

You can throw everything together in Postman if you want, no need to keep hitting up Swagger though it’s a good quick Test / See how things work.

Generally what I would do is

  • Define a Collection
  • If using OAuth I would define authentication on the Collection Folder in one of two ways A) Configuring OAuth with Postman’s out-of-box authentication B) Defining a Pre-request Script that handles Authentication including Renewal
  • If using Basic Auth - Would either define a Authentication Request that I invoke manually with a Tests scripts to capture the response and set the Bearer Token in a Environment Variable
  • Any other Requests would Inherit Authentication from the Parent Folder, or set the Authentication Header referencing the Bearer Token variable.
  • Postman is then used to quickly run collections / Actions when needed, or if I want to do regression testing by define more Tests with assertions

The PowerShell Module or my own scripts I tend to use in my Operational Day to Day, or Implementation MOPs whether those are manual or automated in some fashion, and also working on garnering support to have UiPath.CLI package officially supported by UiPath given its a dependency of Azure DevOps and Jenkins CI/CD and those are officially supported.





1 Like

Many thanks for your detail instructions, and learnt a lot more from the issue itself.


A post was split to a new topic: Changing Default Expiration Timeout

This topic was automatically closed 3 days after the last reply. New replies are no longer allowed.