guides:ws_payloads_retrieve

payloads:retrieve_payload

The payloads web service is a REST structured service that derives its functionality based on syntax used when calling the web service. To retrieve a payload from a repository, call the payloads web service with a repository name and the payload file name.

The payload will be returned in the body of the response as a UTF-8 encoded XML string.

Important: The payload must be locked prior to retrieving it.

Purpose: Retrieve A Payload From A Repository.

Request Endpoint

Method	URL
GET	https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/{repository}/{payload_name}

Variables:

Variable	Usage	Description
{repository}	Required	The name of the repository
{payload_name}	Required	The name of the payload

Request Body

N/A

Request Headers

Key	Value
access_token	{soft-token}

JSON Request Parameters

N/A

Notes:

Any condition that results in an unsuccessful call to the payloads web service will produce a JSON formatted response with a code and message property populated.

Sample Request

Endpoint:

https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/retrieve/standard_testagent1-202007140415-00003.1.1_200723151458170.xml

Sample Response (Note: Most of the Base64 image text was removed for readability.)

Status Code: 200

<?xml version="1.0" encoding="utf-8"?>
<RESPONSE_GROUP PRIAVersionIdentifier="2.4.2">
    <REQUESTING_PARTY _Name="TEST SUBMITTER 1" _StreetAddress="1001 APEX Submission Ave." _StreetAddress2="" _City="Sub City" _State="CA" _PostalCode="91234" _Identifier="35" />
    <SUBMITTING_PARTY LoginAccountIdentifier="bzsub1" _Name="AGENT - TEST AGENT 1" />
    <RESPONSE ResponseDateTime="2020-07-23T14:50:24">
        <KEY _Name="Comment" _Value="Sample comment" />
        <RESPONSE_DATA>
            <PRIA_RESPONSE _RelatedDocumentsIndicator="true">
                <PACKAGE CountyFIPSCode="901" StateFIPSCode="06" SecurityType="1" Priority="Standard">
                    <PRIA_DOCUMENT _Code="Deed" DocumentSequenceIdentifier="1" _UniqueIdentifier="ABC-123" RequestChecksumAlgorithm="SHA384" RequestChecksumValue="0C7580F7-7E3A-4615-A495-55EB66E299A6" ResponseChecksumAlgorithm="SHA384" ResponseChecksumValue="94BE9B16-F97B-4525-BD00-D331F1E7C517">
                        <GRANTOR _FirstName="John" _LastName="Doe" NonPersonEntityIndicator="true" />
                        <GRANTEE _FirstName="Jane" _LastName="Doe" NonPersonEntityIndicator="true" />
                        <RECORDABLE_DOCUMENT>
                            <_ASSOCIATED_DOCUMENT _InstrumentNumber="2009003899200" _RecordingDate="2009-02-25" />
                        </RECORDABLE_DOCUMENT>
                        <EMBEDDED_FILE _PagesCount="3">
                            <DOCUMENT>SUkqAA7qAAAtVZDKI+R4jhkhyPkfI6I6I4hfI4EGAXI4y4UuyODkcUjg5HA+LkR4uKXyOyOFI4YORcyPl2YiOBgjxHZeL5HIuyPnGR4ui6I6I</DOCUMENT>
                        </EMBEDDED_FILE>
                        <STATUS _Code="Rejected">
                            <RECORDING_ERROR _Code="99999" _Description="This is a automatic rejection test message." _OfficersName="John Doe" />
                        </STATUS>
                    </PRIA_DOCUMENT>
                </PACKAGE>
                <RECORDING_TRANSACTION_IDENTIFIER _Value="TESTAGENT1-202007140415-00003.1.1" SecondaryValue="3453453453" />
            </PRIA_RESPONSE>
        </RESPONSE_DATA>
    </RESPONSE>
</RESPONSE_GROUP>

Status Code: 500 (When an error occurs.)

{
    "Exception": {
        "Code": "PayloadFileLockError",
        "Message": "The payload standard_testagent1-202007140415-00003.1.1_200723151458170.xml not locked."
    }
}

Comment 1:

Following is a C# / .NET sample code snippet that shows how to call the web services associated with retrieve a payload from a remote folder/repository and saving it in a local folder.

This snippet was derived from the Web Service Toolbox that is available on the CeRTNA Wiki. The sample application is intended for easy to read demonstration purposes and not production quality code. The Web Service Toolbox application is documented, on the CeRTNA Wiki, to aid in understanding the code snippet shown below.

The general process flow for retrieving a payload from a remote folder is:

Lock the remote payload.
Retrieve the remote payload.
Validate your retrieved payload.
If the validation is successful: Delete the locked remote payload.
Otherwise: Unlock the remote payload. (Troubleshoot or re-retrieve.)

The following snippets show the process, minus the validation, step…

Snippet 1:

private void btnRetrieve_Click(object sender, RoutedEventArgs e)
{
    bool rc;
 
    string strLocalFolder = tbLocalFolderName.Text;
    string strRepository = (cbRepository.SelectedItem as ComboBoxItem).Content as string;
 
    // See payloads:get_repository_file_names web servicefor the following
 
    string[] strFolderFileNames = getRepositoryFileNames(strRepository);
 
    if (strFolderFileNames != null)
    {
        for (int i = 0; i < strFolderFileNames.Length; i++)
        {
            // Lock the payload
            rc = LockUnlockRemoteFile(strRepository, strFolderFileNames[i], "lock");
            // Retrieve the payload
            DownloadRemoteFile(strRepository, strFolderFileNames[i], strLocalFolder);
            // Delete the remote payload
            rc = DeleteRemoteFile(strRepository, strFolderFileNames[i]);
        }
    }
}

Snippet 2: Lock The Payload

private bool LockUnlockRemoteFile(string strRepositoryType, string strFileName, string strAction)
{
    bool rc = false;  //Default
 
    if (strAction == "lock")
    {
        tbMessageLine.Text = "Locking remote file " + strFileName;
    }
    else if (strAction == "unlock")
    {
        tbMessageLine.Text = "Unlocking remote file " + strFileName;
    }
    else
    {
        tbMessageLine.Text = "";
    }
 
    RestClient client = null;
    RestRequest request = null;
    IRestResponse response = null;
 
    string strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/user/login";
 
    // Password has to be hashed.
    // New convention uses a Salt value from the user record
    // See the Login web service for more detail.
 
    string strSalt = GetSalt(tbUserName.Text);
    string strPassword = tbPassword.Password.ToString();
 
    string strHashedPassword = HashPassword(strPassword, strSalt);
 
    string strParms = "{\n\t\"user_name\" : \"";
    strParms += tbUserName.Text;
    strParms += "\",\n\t\"password\" : \"";
    strParms += strHashedPassword;
    strParms += "\"\n}";
 
    client = new RestClient(strURL);
    request = new RestRequest(Method.POST);
 
    request.AddHeader("Cache-Control", "no-cache");
    request.AddHeader("Content-Type", "application/json");
 
    request.AddParameter("Login", strParms, ParameterType.RequestBody);
    response = client.Execute(request);
 
    if (response.IsSuccessful)
    {
        var jsonResult1 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        string token = jsonResult1.access_token;
 
        strURL = null;
        client = null;
        request = null;
        response = null;
 
        strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/" + strRepositoryType + "/" + strFileName + "?operation=" + strAction;  
 
        client = new RestClient(strURL);
        request = new RestRequest(Method.PATCH);
 
        request.AddHeader("Cache-Control", "no-cache");
        request.AddHeader("access_token", token);
        response = client.Execute(request);
 
        if (response.IsSuccessful)
        {
            if (strAction == "lock")
            {
                tbMessageLine.Text = "Remote file " + strFileName + " successfully locked.";
            }
            else if (strAction == "unlock")
            {
                tbMessageLine.Text = "Remote file " + strFileName + " successfully unlocked.";
            }
            else
            {
                tbMessageLine.Text = "";
            }
            rc = true;
        }
        else
        {
            var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
            string strMessage = jsonResult2.Exception.Message;
            tbMessageLine.Clear();
            tbMessageLine.Text = strMessage;
        }
    }
    else
    {
        var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        tbMessageLine.Text = jsonResult2.ToString();
    }
    return (rc);
}

Snippet 3: Retrieve The Payload

private void DownloadRemoteFile(string strRepositoryType, string strFileName, string strLocalFolder)
{
    tbMessageLine.Text = "";
 
    RestClient client = null;
    RestRequest request = null;
    IRestResponse response = null;
 
    string strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/user/login";
 
    // Password has to be hashed.
    // New convention uses a Salt value from the user record
    // See the Login web service for more detail
 
    string strSalt = GetSalt(tbUserName.Text);
    string strPassword = tbPassword.Password.ToString();
 
    string strHashedPassword = HashPassword(strPassword, strSalt);
 
    string strParms = "{\n\t\"user_name\" : \"";
    strParms += tbUserName.Text;
    strParms += "\",\n\t\"password\" : \"";
    strParms += strHashedPassword;
    strParms += "\"\n}";
 
    client = new RestClient(strURL);
    request = new RestRequest(Method.POST);
 
    request.AddHeader("Cache-Control", "no-cache");
    request.AddHeader("Content-Type", "application/json");
 
    request.AddParameter("Login", strParms, ParameterType.RequestBody);
    response = client.Execute(request);
 
    if (response.IsSuccessful)
    {
        var jsonResult1 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        string token = jsonResult1.access_token;
 
        strURL = null;
        client = null;
        request = null;
        response = null;
 
        strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/" + strRepositoryType + "/" + strFileName;  
 
        client = new RestClient(strURL);
        request = new RestRequest(Method.GET);
 
        request.AddHeader("Cache-Control", "no-cache");
        request.AddHeader("access_token", token);
        request.AddHeader("Content-Type", "text/plain");
        response = client.Execute(request);
 
        if (response.IsSuccessful)
        {
            // Note: Do not try to use the LoadXml API as it does not account for the encoding preamble.
 
            XmlReader myXmlReader = XmlReader.Create(new MemoryStream(Encoding.UTF8.GetBytes(response.Content)));
            XmlDocument xmlDoc = new XmlDocument();
            xmlDoc.Load(myXmlReader);
            xmlDoc.Save(strLocalFolder + "\\" + strFileName);
        }
        else
        {
            var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
            string strMessage = jsonResult2.Exception.Message;
            tbMessageLine.Text = strMessage;
        }
    }
    else
    {
        var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        tbMessageLine.Text = jsonResult2.ToString();
    }
}

Snippet 4: Delete The Remote Payload

private bool DeleteRemoteFile(string strRepositoryType, string strFileName)
{
    tbMessageLine.Text = "Deleting remote file " + strFileName;
 
    bool rc = false;
 
    RestClient client = null;
    RestRequest request = null;
    IRestResponse response = null;
 
    string strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/user/login";
 
    // Password has to be hashed.
    // New convention uses a Salt value from the user record
    // See the Login web service for more detail
 
    string strSalt = GetSalt(tbUserName.Text);
    string strPassword = tbPassword.Password.ToString();
 
    string strHashedPassword = HashPassword(strPassword, strSalt);
 
    string strParms = "{\n\t\"user_name\" : \"";
    strParms += tbUserName.Text;
    strParms += "\",\n\t\"password\" : \"";
    strParms += strHashedPassword;
    strParms += "\"\n}";
 
    client = new RestClient(strURL);
    request = new RestRequest(Method.POST);
 
    request.AddHeader("Cache-Control", "no-cache");
    request.AddHeader("Content-Type", "application/json");
 
    request.AddParameter("Login", strParms, ParameterType.RequestBody);
    response = client.Execute(request);
 
    if (response.IsSuccessful)
    {
        var jsonResult1 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        string token = jsonResult1.access_token;
 
        strURL = null;
        client = null;
        request = null;
        response = null;
 
        strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/" + strRepositoryType + "/" + strFileName; 
 
        client = new RestClient(strURL);
        request = new RestRequest(Method.DELETE);
 
        request.AddHeader("Cache-Control", "no-cache");
        request.AddHeader("access_token", token);
        response = client.Execute(request);
 
        if (response.IsSuccessful)
        {
            tbMessageLine.Text = "Remote file " + strFileName + " successfully retrieved. Remote file deleted.";
            rc = true;
        }
        else
        {
            var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
            string strMessage = jsonResult2.Exception.Message;
            tbMessageLine.Text = strMessage;
        }
    }
    else
    {
        var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        tbMessageLine.Text = jsonResult2.ToString();
    }
    return (rc);
}

Comment 2:

A nice utility for experimenting with web service calls is POSTMAN. You can download a free version of POSTMAN from the following URL: https://www.getpostman.com/apps