☰
Navigation :

Special Datasets & Jarvis Login

Jarvis URLs

The following section outlines the implementation and usage of various default deployed Jarvis URLs and their behaviour.

The following examples assume that:

The __status Dataset

The __status dataset (with two leading underscores) is a special dataset which allows your application to determine the user’s login status without actually performing a data request.

To access the __status dataset in your web browser, send a GET request to the following URL.

http://localhost/jarvis-agent/demo/__status

This is a specific example of the general Jarvis URL format which is.

http://localhost/jarvis-agent/<app-name>/<dataset>[/<p1>[/<p2>...]]

This is a RESTful URL which specifies an application name demo, then a dataset within that application. If Jarvis and the demo app are correctly configured, then the response should be JavaScript Object Notation (JSON) response with a Content-Type of plain/text.

{
   "error_string" : "",
   "logged_in"    : 1,
   "group_list"   : "admin",
   "username"     : "admin"
}

This is a response object with four attributes.

When logged_in = 0, username and group_list will always be empty and the error_string will be a non-empty description of why the login failed.

Conversely if logged_in = 1 then the error_string will always be empty, username will always be non-empty, and group_list contains a possibly zero-length comma-separated list of groups.

Note: It is not always necessary to be logged in to access a dataset. The special datasets are available to non-logged-in users. Dataset creators may offer user-defined datasets to non-logged-in users by specifying ** as the access string in the dataset XML definition.

To receive responses in XML format, either configure the default format as xml in the demo.xml file, or pass format as a CGI parameter. E.g.

http://localhost/jarvis-agent/demo/__status?

The response is also Content-Type plain/text but with XML content. The same object is returned as in the JSON case, but in XML.

<?xml version="1.0" encoding="iso-8859-1" ?>
<?meta name="GENERATOR" content="XML::Smart/1.6.9 Perl/5.010000 [linux]" ?>
<response error_string="" group_list="admin" logged_in="1" username="admin"/>

The __habitat Dataset

The __habitat dataset provides a simple method for an application configuration file to pass some of its configuration directly back to the client application instance.

Note: All Habitat content is public; Login is not required in order to view the habitat.

The habitat is configured in the applications configuration file. The habitat is returned essentially verbatim, however there a difference between JSON and XML habitat returned handling.

JSON Habitat

This is how you might define a JSON habitat. If your requested format is non-XML (e.g. JSON), we will strip the outer tags for you.

<jarvis>
    <app>
        <habitat>
            <![CDATA[
                hargs: {
                    install_type: 'production'
                }
            ]]>
        </habitat>
        ...

The return from the query:

http://localhost/jarvis-agent/demo/__habitat?format=json

will be:

hargs: {
    install_type: 'production'
}

XML Habitat

In the XML case, the habitat is returned as an XML object, parsed and then re-encoded. This means that the habitat returned will be logically equivalent, but may not necessarily be byte-for-byte equivalent to what is defined in the application configuration file.

<jarvis>
    <app>
        <habitat>
            <install_type>production</install_type>
            <parameter name="pname" value="some_value"/>
            <parameter name="another" value="a_different_value"/>
        </habitat>
        ...

With the above habitat, requesting in XML:

http://localhost/jarvis-agent/demo/__habitat?format=xml

The result returned to the client will be:

<install_type>production</install_type>
<parameter name="pname" value="some_value"/>
<parameter name="another" value="a_different_value"/>

The __logout Dataset

Invoking the __logout dataset will cause the server-side session ID to be erased from the session store.

Note: when using the None Login module, erasing the cookie is all well and good, but the very next request will always automatically re-login and create a new cookie and session ID.

Logging-In to Jarvis

Using the __status and __logout datasets, you can login and logout of Jarvis.

To login to Jarvis, make any request to Jarvis, and include the following parameters:

Jarvis will perform the configured login process, and will always create a server-side session.

The session ID will be returned in the response headers as a cookie. The default cookie name is CGISESSID. This can be configured to avoid conflict if multiple applications are using session cookies on the same server.

Even if the login fails, a session cookie will still be returned. For maximum efficiency and security, your application should supply username and password only on the very first request, and should pass the session cookie subsequently. The session cookie lifetime will be extended on every successful request. The exception to this is exec and plugin requests which create their own response headers.

Any request may be used to perform session login. However, the convention is to only perform login as part of a __status request.

Note: the __status response parameters (error_string, logged_in, username, group_list) are also included in data fetch results returned by Jarvis. However, they are not included in the responses to dataset modification requests.

Jarvis Error Responses

Exception handing is an important part of any application, especially so when dealing with client/server web-services.

Compilation Failure

When the Jarvis scripts fail to compile, you will receive a 500 Internal Server Error generated by Apache.

Authorization Required

When access is requested to a resource which requires login, or which requires membership of a group not in the current user’s group list, then a 401 Unauthorized is returned with a text/plain content body which describes the failure reason. It may also include the script line number.

The calling application should invoke the __status dataset to ensure that the user is logged-in, and log them in if required.

No Such Dataset

When access is requested to a dataset which does not match a plugin, exec, special dataset, or regular dataset, then a 404 Not Found is returned with a text/plain content body which names the not-found dataset. It may also include the script line number.

Request/Configuration Error

Otherwise, if Jarvis compiles but identifies a fatal problem not related to dataset access permissions or unknown dataset, it will return a Jarvis-generated 500 Internal Server Error request, with a response body which gives a description of the problem.

Store Errors

Store errors are errors related to the actual user-supplied data values being rejected by the database. These occur when Jarvis cannot insert/update/delete data due to primary key, foreign key, unique constraints or bad type.

In such cases, if the application configuration option http_code_on_store_error is set to no, a 200 Success result is returned, but the success attribute in the returned JSON or XML will indicate the failure, and a message parameter will indicate the reasons.

If however the http_code_on_store_error option is set to yes, then a 500 error is returned to the client with the content of the response formatted as instructed by the error_response_format option.