SDK

For easier integration against the portal, a Software Development Kit (SDK) can be used. The SDK is a .NET assembly that can be used as a referens in a customized .NET project. The SDK can be established through the assembly named "Pointsharp.NiS.Portal.SDK.dll".

The SDK will take care of the login process and the security operations when call the API of the portal.

Its possible to create a new instance of the SDK with the URL against the API of the portal and then use the instance with several methods for a full integration.

Example 1. Example of instance
Client client = new Client("http://server/NiS/PortalAPI/ServiceSoap.svc");

client.SetCertificateHash("59c4a02b4d62418f4a6e3df30e36a1b1dbbc0053");
client.InvokeLogin();
client.InvokeLogout();

Available methods

SetCertificateHash()

Sets the hash of the certificate used for login into the system.

SetCertificateHashTls()

Sets the hash of the certificate used for SSL/TLS authentication of the web service.

SetCompressionAlgorithm()

Sets the compression algorithm (e.g. GZ). This is automatically set when call the InvokeLogin() method.

SetEncryptionAlgorithm()

Sets the encryption algorithm (e.g. AES). This is automatically set when call the InvokeLogin() method. Note that AES is required if using ECC certificates for logon.

SetEncryptionLength()

Sets the length of the encryption (e.g. 256). This is automatically set when call the InvokeLogin() method.

SetHashAlgorithm()

Sets the OID of the signature hash algorithm (e.g. 2.16.840.1.101.3.4.2.1). This is automatically set when call the InvokeLogin() method.

SetServerUrl()

Sets the URL to the server instance. This can be used for different call when using the REST-service (e.g. "/api/object/get" or "/api/task/get").

SetBehalfOfId()

Sets the entity id behalf of the logged in user.

SetCounter()

Sets the new counter for each call.

GetCounter()

Gets the current counter for the last call.

InvokeLogin()

Login into the system. The method returns the session id of the login instance.

InvokeLogout()

Logout from the system. The method returns the response from the server.

InvokeRequest()

Send request to the system. The method returns the response from the server.

Examples

SOAP request and response

Example 2. SOAP request and response for Login, Get a user with ID 3, and Logout

This is an example of a SOAP request and SOAP response doing the following operations:

  1. Login

  2. Get a user with ID 3

  3. Logout

  • SOAP request (C#)

  • SOAP response (XML)

public void Connect()
{
    Client client = new Client("http://localhost/NiS/PortalAPI/ServiceSoap.svc"); (1)

    client.SetCertificateHash("59c4a02b4d62418f4a6e3df30e36a1b1dbbc0053"); (2)

    String sessionId = client.InvokeLogin(); (3)

    Int32 counter = client.GetCounter() + 1; (4)
    client.SetCounter(counter);

    String request = (5)
        "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
        "<soap:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">"
        "<soap:Body>"
        "<GetObject xmlns=\"http://www.pointsharp.com/netid/server/portal\">"
        "<Info>"
        "<SessionId>" + sessionId + "</SessionId>"
        "<Type>User</Type>"
        "<Id>3</Id>"
        "<Count>" + counter + "</Count>"
        "</Info>"
        "</GetObject>"
        "</soap:Body>"
        "</soap:Envelope>";

    String response = client.InvokeRequest(request); (6)

    client.InvokeLogout(); (7)
}
1 Create the new instance with the URL against the server.
2 Set the hash of the login certificate.
3 Invoke the login operation and get the session id.
4 Increase the counter for every call with 1. First call must always be 1.
5 Create a request as SOAP (e.g. get user with id 3).
6 Invoke the request and get the response.
7 Logout from the system. 
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <GetObjectResponse xmlns="http://www.pointsharp.com/netid/server/portal">
            <GetObjectResult>
                <Info>
                    <User>
                        <Id>3</Id>
                        <Name>John Doe</Name>
                        <EmploymentType>PermanentContract</EmploymentType>
                        <SerialNumber>123456789</SerialNumber>
                        <Phone>0707661495</Phone>
                        <Email>john.doe@contoso.com</Email>
                        <OrganizationName>Contoso Ltd</OrganizationName>
                    </User>
                    <Status>
                        <Code>Success</Code>
                        <Description>Success</Description>
                    </Status>
                </Info>
            </GetObjectResult>
        </GetObjectResponse>
    </s:Body>
</s:Envelope>

REST request and response

Example 3. REST request and response for Login, Get a user with ID 3, and Logout

Example of a REST request and response doing the following operations:

  • Login

  • Get a user with ID 3

  • Logout

  • REST request (C#)

  • REST request (PowerShell)

  • REST response (JSON)

public void Connect()
{
    Client client = new Client("http://localhost/NiS/PortalAPI/ServiceRest.svc/api/object/get"); (1)

    client.SetCertificateHash("59c4a02b4d62418f4a6e3df30e36a1b1dbbc0053"); (2)

    String sessionId = client.InvokeLogin(); (3)

    Int32 counter = client.GetCounter() + 1; (4)
    client.SetCounter(counter);

    String request = (5)
      {
        "SessionId":" + sessionId + ",
        "Type":"User",
        "Id":"3",
        "Count":" + counter + "
      }

    String response = client.InvokeRequest(request); (6)

    client.InvokeLogout(); (7)
}
1 Create the new instance with the URL against the server.
2 Set the hash of the login certificate.
3 Invoke the login operation and get the session id.
4 Increase the counter for every call with 1. First call must always be 1.
5 Create a request as REST (e.g. get user with id 3).
6 Invoke the request and get the response.
7 Logout from the system. 
Add-Type -Path "Pointsharp.NiS.Portal.SDK.dll"

$client = [Pointsharp.NiS.Portal.SDK.Client]::new("http://localhost/NiS/PortalAPI/ServiceRest.svc/api/object/get") (1)

$client.SetCertificateHash("59c4a02b4d62418f4a6e3df30e36a1b1dbbc0053") (2)

$sessionId = $client.InvokeLogin() (3)

$counter = $client.GetCounter() + 1 (4)
$client.SetCounter($counter)

$client.InvokeRequest("{""SessionId"":""" + $sessionId + """,""Type"":""User"",""Id"":""3"",""Count"":""" + $counter + """}") (5)

$client.InvokeLogout() (6)
1 Create the new instance with the URL against the server.
2 Set the hash of the login certificate.
3 Invoke the login operation and get the session id.
4 Increase the counter for every call with 1. First call must always be 1.
5 Invoke the request and get the response.
6 Logout from the system. 
{
    "User": {
        "Id": "3",
        "Name": "John Doe",
        "EmploymentType": "PermanentContract",
        "SerialNumber": "123456789",
        "Phone": "0707661495",
        "Email": "john.doe@contoso.com",
        "OrganizationName": "Contoso Ltd"
    },
    "Status": {
        "Code": "Success",
        "Description": "Success"
    }
}