Building the Query String

Top  Previous  Next

The URL to be called in order to authenticate against z/Scope Anywhere externally should follow the format below:

 

http://127.0.0.1:8023/asp/?*<queryString>

 

The query string may contain all the information related to the server credentials, connection to be started, host credentials and any other information you want to use within the connection macros.

 

Follow the topics below and learn how to create the query string in order to perform the two authentication levels (z/Scope Anywhere Server and host) as well as use external data to perform any other automation task through (macros):

 

z/Scope Anywhere Server Authentication:

 

The authentication against z/Scope Anywhere from external applications can be done using: username and password or username and an ApiKey

In order to authenticate you must send the combination of the _userid variable and _password or _apikey inside the queryString.

 

1. _userid=<UserId>&_password=<Password>
2. _userid=<UserId>&_apikey=<APIKey>

 

Please, make sure the underscore is placed before the userid and password/apikey parameter names.

You have to replace <UserId> with the username you want to logon and <APIKey> or <Password> with the corresponding ApiKey/Password z/Anywhere is expecting. For example, if the server username was "john" and his password "john123", the URL followed by the query string would be:

 

http://127.0.0.1:8023/asp/?_userid=John&_password=John123

 

 

Starting a Connection:

 

If you want to open a particular connection, you can add to the query string the  "start" parameter. This parameter works as an "autostart" command. If we wanted to start a connection called "MyConnection", the query string above would became this one:

 

http://127.0.0.1:8023/asp/?_userid=John&_password=John123&start=MyConnection

 

Hiding the connections start panel:

 

You can make z/Anywhere jump the start panel and go straight to the connection that autostarted by sending the hsp parameter = 1.

This parameter only makes sense if a Connection will be started automatically.

 

http://127.0.0.1:8023/asp/?_userid=John&_password=John123&start=MyConnection&_asuser=hostUser&_aspass=hostPassword&hsp=1

 

 

Authenticating against the host:

 

Once a connection is automatically open it is possible to login automatically to the host. To do that you should send the host credentials on the query string and have a login macro associated the connection autostart setting.

The parameters to authenticate against the host could have any name of your preference, let's suppose you are going to name them _asuser and _aspass. The query string should look like this:

 

http://127.0.0.1:8023/asp/?_userid=John&_password=John123&start=MyConnection&_asuser=hostUser&_aspass=hostPassword

 

 

Adding other information to be used on the connection macros:

 

Besides de host username and password, z/Scope Anywhere enables you to send any other parameter within the query string so that you can use them to program macros. The parameters names should have a prefixed underscore and should not match the reserved parameters "userid" and "apikey".

 

_myIntParam=1500&_myStrParam=Hello World&_myBoolParam=true

 

On the Integration a login macro section you will find a example on how to send parameters within the query string and use them to perform a login automation. The same principles of sending and using external application data covered on the example, can be applied to perform any other macro automation task.

 

 

Encrypting the query string information:

 

Before deploying your application, it is strongly recommended that you encrypt all the exchanged query string data, by using a Diffie Hellman Key Exchange provided by z/Scope Anywhere.

 

Read more:

Apikey
Diffie Hellman Key Exchange
Using z/Scope Anywhere In-Memory Dictionary
Integrating a Login Macro
C# External Authentiation Demo
Web Authentication Provider