samstatus (Retrieve status of a SAM pool)

Retrieves the status of all user IDS in the SAM pool.

samstatus returns whether IDs are logged in, marked as free (available for a new process) or busy (allocated to a process), or marked (instructed to log out the next time the ID is released and free). samstatus can assess the health of your pool and determine whether you need to issue resetpool.

Issuing samstatus does not actually log in the requesting ID. samstatus can be issued by the SAM pool group owner or the company administrator of a SAM pool group owner.

Note: samstatus is a newer feature and may not be available yet for all sessions.

Query string

The query string in the HTTP header must contain the following parameters:

api
Specify the name of the API transaction.
apiversion
Specify the version of the API that should handle the requested transaction.

For the most up-to-date version, use apiversion=3.

uid
Specify a valid 1010data user name.
pswd
Specify a valid unencrypted 1010data password for the 1010data user name provided to the uid parameter.

The response from the login transaction will provide an encrypted password, which must be supplied as the value for the pswd attribute for all the other transactions.

gid
The group identifier for the SAM pool. In the 1010data Insights Platform, a SAM pool is a group containing some number of UIDs. A valid gid follows the same rules as a valid uid.
kill (optional)
Valid values for kill are as follows:
yes
Terminate the existing session and start a new one.
no
Do not terminate the existing session.

If no session exists, a new one will be created. If a session does exist, an error is returned.

Note: If kill=no and a session is active, the system returns an error.
possess
Log in and possess the existing session.
auth
Authenticate with the system but do not kill, possess, or start any session.

The default is yes.

XML input to server

No XML input is required. All data for the transaction is specified in the connection string.

XML response from server

A successful result contains the following elements:

<rc>
The return code generated by the transaction. For a list of return codes, see Return codes.
<msg>
The message returned by the system. Specific messages correspond to specific return codes.

Query string example

https://www2.1010data.com/gw.k?api=samstatus&apiversion=3&uid=$UID&pswd=$PSWD&gid=$GID

samstatus example

Request:
https://www2.1010data.com/gw?apiversion=3&api=samstatus
    &uid=clientx_admin&pswd=xxxxx&gid=clientx

Response:
<out>
<rc>0</rc>
<gid gid="clientx">
<uid uid="clientx_1" free="1" loggedin="0" marked="0"/>
<uid uid="clientx_2" free="1" loggedin="1" marked="0"/>
<uid uid="clientx_3" free="0" loggedin="1" marked="0"/>
</gid>
</out>

samstatus shows that in the SAM pool group clientx, clientx_1 is not logged in and free, clientx_2 is logged in and free for a new process, and clientx_3 is logged in and allocated to a process (busy).