Clearing the ArcGIS Services Directory cache "the easy way"

In ArcGIS Server 10, we added new options to clear the cache of your Services Directory more conveniently. This is not widely known, so I thought I would share with you what it’s about.

As you may know, the ArcGIS Services Directory caches information about your GIS services. This accelerates startup time of your Web applications and makes your server more responsive. The downside is that when you create, remove, or update your GIS services, you need to clear your Services Directory cache. Otherwise, your changes would not be visible to your apps.

To clear the Services Directory cache, you need to log in to the ArcGIS REST admin page with your GIS server administrator password, which is inconvenient when you are developing apps and services and continually making changes.

In ArcGIS Server 10, you can clear the cache with a REST call to your server. This makes it possible to clear the cache with a simple click. This REST call needs to carry a token to make sure that the request is legitimate.

Here’s how you make this happen. First, go to the admin page of your Services Directory. It is generally http://yourserver/arcgis/rest/admin, although the ArcGIS Server instance name (in our example “arcgis”) may vary if you didn’t choose the default name.

REST admin page 

You will notice a new link in ArcGIS Server 10 named Generate Token Options. Click it to see this page:

Generate admin token page 

Tokens are valid for a specific IP address or Web application URL. If you chose an IP, your token will only work when the request to clear the cache is issued from that specific IP. For example, this could be the IP of the machine from which you are developing your apps. You can even restrict it more by creating a token that only is valid for a very specific URL. You will notice that there is a handy option that makes a valid token for the IP from which you are currently working.

Type your ArcGIS Server admin user and password. For the expiration date, you probably want something like a month, or even a year. For the output format, I normally pick JSON, and you will soon see why. Click Generate Admin Token.

Returned token

The JSON output is handy, because now you can easily copy the token string. Make sure to leave out the quotes at the beginning and end of the token string.

Now, just to test, open a Web browser and type a URL like this in the address bar, substituting your own server name and token:

http://yourServer/ArcGIS/rest/admin/cache/clear?token=_w1MmNsrSudZQbfCKUAELuFTETJvPhMFt1J5AuX8wfxe6HW2fCH1a6yJ4EldjIXV&f=json

Note that you’re making the admin/cache/clear REST call, followed by your token (to authenticate against the server with your ArcGIS Server Administrator user). Finally, you add &f=json to ask for the response to come in JSON format.

This will clear the Services Directory cache and give you back a simple JSON {“success”:”true”} message in the browser. If you get an error, the most likely cause is that the token is not being used from the IP or specific URL you created it for, or it may be because the token expired already. Errors can also occur if you failed to copy and paste the token string completely or correctly.

From this point, you probably know what to do. You simply create an HTML page with a link to the clear cache URL. Then, just click the link whenever you want to clear the cache. Remember that the HTML page should be hosted in the Web server with the IP for which you created the token.

Just to make things easier, here is a template you can follow for the HTML page:

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Refresh ArcGIS Services Directory</title>
</head>
<body>
<a href='http://YOURSERVER/ArcGIS/rest/admin/cache/clear?token=YOURTOKEN&f=json'>Click here to clear your ArcGIS Services Directory Cache<a>
</body>
</html>

You do not want to expose this link to end users, of course. Keep this under your control so nobody clears the cache accidentally. Otherwise, you will force the server to populate the Services Directory information more frequently, slowing down your apps significantly.

Contributed by Ismael Chivite of the ArcGIS Server product management team

This entry was posted in Services and tagged , . Bookmark the permalink.

Leave a Reply

6 Comments

  1. marwood says:

    Hello,

    I am trying this and generating a valid token. However, when I try the URL I get the following error:

    {“error”:{“code”:498,”message”:”Invalid admin token”,”details”:[]}}

    Please can you help?

    Thanks
    Andy

  2. hazelton_glenn says:

    if the services are restarted every morning does that clear the cache or is this step needed as well?

    also i am unclear about how to create an html page that calls the url. can you explain a bit more please.

  3. Ismael says:

    To John and Hazelton_glenn: In a production environment, you should not enable a regular update of your cache. In fact, you should only update it when a service has been added, deleted or updated. By updated I mean something like adding new layers to the map service, changing their symbology etc
    The request from a client that comes inmediatly after you clear the cache will take a good amount of time to resolve. And most of this time will be actually spent by the server populating that cache again.

    So ideally, in a production environment you should set your recycling to ‘manual’ which is the default.

    Restarting a service does not require you to clear the cache, as it does not adding or removing data (rows/features) from the tables/layers used in your map service. Hope this is of help,

    Ismael

  4. Ismael says:

    to hazelton and marwood: The blog post has been updated to hopefully address your questions. Thanks for your interest! Ismael

  5. marwood says:

    Ismael,

    Sorry but I can’t see a reply to my post about the error I am getting trying to genereate a token.

    Please can you help?

    Thanks
    Andy

  6. jdcoles says:

    I have a Developer’s Guide that was written by Moxie Zhang, November 21, 2008. Has this been updated?